diff --git a/docs/source/introduction.rst b/docs/source/analysis.rst similarity index 96% rename from docs/source/introduction.rst rename to docs/source/analysis.rst index b3b31c9..66d0d16 100644 --- a/docs/source/introduction.rst +++ b/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 diff --git a/docs/source/conf.py b/docs/source/conf.py index c22eda7..20a20b5 100644 --- a/docs/source/conf.py +++ b/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 = { diff --git a/docs/source/index.rst b/docs/source/index.rst index 4b07d22..a910408 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -4,48 +4,95 @@ Performance, Portability, and Productivity Analysis Library .. toctree:: :maxdepth: 1 :hidden: + :caption: Introduction - introduction + Getting Started + 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 + GitHub 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 ` like "performance portability" and + "code divergence" to quantify the trade-offs between performance, portability + and productivity made by applications targeting multiple platforms. + +- :doc:`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 `__, 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 `__. -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 diff --git a/docs/source/p3-analysis-flowchart.svg b/docs/source/p3-analysis-flowchart.svg index bd2c048..85f1c07 100644 --- a/docs/source/p3-analysis-flowchart.svg +++ b/docs/source/p3-analysis-flowchart.svg @@ -145,6 +145,13 @@ inkscape:groupmode="layer" id="layer1" transform="translate(-10.173512,-10.630526)"> +