Merge pull request #47 from Pennycook/update-docs-theme

Update documentation theme

docs/source/introduction.rst → docs/source/analysis.rst

@@ -1,5 +1,5 @@
-Introduction to P3 Analysis
-===========================
+P3 Analysis
+===========
 
 The goal of P3 analysis is to understand the interaction of application
 performance, application portability and developer productivity. Using
@@ -26,7 +26,7 @@ The terminology used by the P3 Analysis Library was first introduced in
 **Platform**
   A collection of software and hardware on which an *application* may run a
   *problem*.
- 
+
 **Application Efficiency**
   The performance of an *application*, measured relative to the best known
   performance previously demonstrated for solving the same *problem* on the

docs/source/conf.py

@@ -1,4 +1,3 @@
-# -*- coding: utf-8 -*-
 #
 # Configuration file for the Sphinx documentation builder.
 #
@@ -79,15 +78,13 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+html_theme = 'furo'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
-html_theme_options = {
-    "fixed_sidebar": True,
-}
+html_theme_options = {}
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
@@ -104,6 +101,8 @@
 #
 # html_sidebars = {}
 
+html_title = "P3 Analysis Library"
+
 
 # -- Options for HTMLHelp output ---------------------------------------------
 
@@ -135,9 +134,11 @@
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'p3-analysis-library.tex',
-     'P3 Analysis Library Documentation',
-     'Intel Corporation', 'manual'),
+    (
+        master_doc, 'p3-analysis-library.tex',
+        'P3 Analysis Library Documentation',
+        'Intel Corporation', 'manual',
+    ),
 ]
 
 
@@ -146,8 +147,10 @@
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    (master_doc, 'p3-analysis-library', 'P3 Analysis Library Documentation',
-     [author], 1)
+    (
+        master_doc, 'p3-analysis-library', 'P3 Analysis Library Documentation',
+        [author], 1,
+    ),
 ]
 
 
@@ -157,10 +160,12 @@
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'p3-analysis-library', 'P3 Analysis Library Documentation',
-     author, 'p3-analysis-library',
-     'A library simplifying the collection and interpretation of P3 data.',
-     'Miscellaneous'),
+    (
+        master_doc, 'p3-analysis-library', 'P3 Analysis Library Documentation',
+        author, 'p3-analysis-library',
+        'A library simplifying the collection and interpretation of P3 data.',
+        'Miscellaneous',
+    ),
 ]
 
 
@@ -186,7 +191,8 @@
 
 from sphinx_gallery.scrapers import matplotlib_scraper
 
-class tight_scraper(object):
+
+class tight_scraper:
 
     def __repr__(self):
         return self.__class__.__name__
@@ -197,7 +203,7 @@ def __call__(self, *args, **kwargs):
 sphinx_gallery_conf = {
      'examples_dirs': ['../../examples','../../case-studies'],
      'gallery_dirs': ['examples','case-studies'],
-     'image_scrapers': (tight_scraper(), ),
+     'image_scrapers': (tight_scraper(),),
 }
 
 intersphinx_mapping = {

docs/source/index.rst

@@ -4,48 +4,95 @@ Performance, Portability, and Productivity Analysis Library
 .. toctree::
    :maxdepth: 1
    :hidden:
+   :caption: Introduction
 
-   introduction
+   Getting Started <self>
+   analysis
    data
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+   :caption: Tutorial
+
    examples/index
    case-studies/index
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+   :caption: Reference
+
    p3
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+   :caption: Contributing
+
+   How to Contribute <https://github.com/intel/p3-analysis-library/blob/main/CONTRIBUTING.md>
+   GitHub <https://github.com/intel/p3-analysis-library>
    notices-and-disclaimers
 
 The Performance, Portability, and Productivity Analysis Library (P3 Analysis
 Library) enables a simpler workflow for the collection and interpretation of P3
 data.
 
+- Compute :doc:`metrics <p3.metrics>` like "performance portability" and
+  "code divergence" to quantify the trade-offs between performance, portability
+  and productivity made by applications targeting multiple platforms.
+
+- :doc:`Plot <p3.plot>` cascades and navigation charts to visualize and gain
+  deeper insight into the "performance portability" and "code divergence"
+  scores achieved by different applications.
+
+
+Installation
+############
+
+The latest release of the P3 Analysis Library is version 0.1.0-alpha. To
+download and install this release, run the following::
+
+    $ git clone --branch v0.1.0-alpha https://github.com/intel/p3-analysis-library.git
+    $ cd p3-analysis-library
+    $ pip install .
+
+We strongly recommend installing the P3 Analysis Library within a `virtual
+environment`_.
+
+.. _`virtual environment`: https://docs.python.org/3/library/venv.html
+
+
 Getting Started
 ###############
 
-- `Introduction to P3 Analysis`_
-- `Collecting P3 Data`_
+As a library, the P3 Analysis Library does not provide user-facing scripts for
+preset analyses. Rather, the library provides routines for manipulating and
+visualizing data in support of common P3 analysis tasks.
 
-.. _Introduction to P3 Analysis: introduction.html
-.. _Collecting P3 Data: data.html
+Using the P3 Analysis Library effectively requires:
 
-Examples
-########
+1. **A basic understanding of P3 analysis and related terminology.**
 
-Simple examples of using the library are available on the `examples`_ page.
-Complete end-to-end examples, using real data, are available on the `case
-studies`_ page.
+   A brief refresher can be found `here <analysis.html>`__, and a high-level
+   overview can be found in papers like
+   "`Navigating Performance, Portability and Productivity`_".
 
-.. _examples: examples/index.html
-.. _case studies: case-studies/index.html
+   .. _here: analysis.html
+   .. _Navigating Performance, Portability and Productivity: https://doi.org/10.1109/MCSE.2021.3097276
 
-Documentation
-#############
+2. **P3 data stored in one of the expected formats.**
 
-- `Package Reference`_
+   The library does not interact with the filesystem, and expects data to be
+   prepared and stored in `Pandas`_ DataFrames with specific column names.
 
-.. _Package Reference: p3.html
+   A guide for collecting and structuring P3 data can be found `here <data.html>`__.
 
-Contribute
-##########
+   .. _Pandas: https://pandas.pydata.org/
 
-Contributions to the P3 Analysis Library are welcome in the form of issues and
-pull requests. Please see the `GitHub repository`_ for more information.
+Simple examples of using the library are available on the `examples`_ page.
+Complete end-to-end examples, using real data, are available on the `case
+studies`_ page.
 
-.. _GitHub repository: https://github.com/intel/p3-analysis-library/blob/main/CONTRIBUTING.md
+.. _examples: examples/index.html
+.. _case studies: case-studies/index.html