doc: restructuring

.gitignore

@@ -25,4 +25,6 @@ benchmarks/reactiondiffusion/csharp_numcil/src/obj
 benchmarks/shallow_water/csharp_numcil/src/obj
 benchmarks/xraysim/python_numpy/materials
 
+doc/source/autodoc_benchmarks/*.rst
+
 *.userprefs

benchpress/__init__.py

@@ -1,5 +1,17 @@
 # -*- coding: utf-8 -*-
+"""
+===========================================
+Benchpress: a benchmark tool and collection
+===========================================
 
+Benchpress is primarily a tool for running benchmarks and analyze/visualize the result.
+
+The workflow:
+    - Write a Python program that generates the commands to run and write the commands to a JSON file
+    - Use `bp-run` to *run* the JSON file
+    - Use a visualizer such as `bp-cli` or `bp-chart` to visualize the results within the JSON file
+
+"""
 from pkg_resources import get_distribution, DistributionNotFound
 import util
 import visualizer

benchpress/benchpress.py

@@ -53,11 +53,6 @@ def _bash_job(cmd, nruns=1):
 def create_suite(cmd_list):
     """Create a suite file (JSON) based on a list of commands
     
-    A command is a Python `dict` with the keys:
-        {'label': 'Human readable label', 
-         'cmd': 'the bash command to execute, 
-         'env': 'a `dict` of environment variables to define before execution'}
-    
     Parameters
     ----------
     cmd_list : list of dict
@@ -98,11 +93,7 @@ def create_suite(cmd_list):
 def command(cmd, label, env={}):
     """Create a Benchpress command, which define a single benchmark execution
 
-    This is a help function to create a Benchpress command:
-    A Benchpress command is a Python `dict` with the keys:
-        {'label': 'Human readable label', 
-         'cmd': 'the bash command to execute, 
-         'env': 'a `dict` of environment variables to define before execution'}
+    This is a help function to create a Benchpress command, which is a Python `dict` of the parameters given.
 
     Parameters
     ----------

benchpress/suite_util.py

@@ -1,4 +1,8 @@
 # -*- coding: utf-8 -*-
+"""
+Utilities for Generating Commands 
+---------------------------------
+"""
 
 import os
 from os.path import join, realpath

doc/requirements.txt

@@ -3,3 +3,4 @@ Pygments>=2.0
 Sphinx
 sphinx_rtd_theme
 sphinxcontrib-bibtex
+pkg_resources

doc/source/autodoc_benchmarks.py

@@ -331,8 +331,12 @@ def implementations(search_path, verbose=False):
 def main():
     benchmarks = implementations(os.path.join(_script_path(), "..", "..", "benchmarks"))
 
+    out_dir = os.path.join(_script_path(), "autodoc_benchmarks")
+    if not os.path.exists(out_dir):
+        os.makedirs(out_dir)
+
     index = benchmark_index(benchmarks)
-    with open(os.path.join(_script_path(), "benchmarks", "autodoc_index.rst"), 'w') as fd:
+    with open(os.path.join(out_dir, "autodoc_index.rst"), 'w') as fd:
         fd.write("==========\n")
         fd.write("Benchmarks\n")
         fd.write("==========\n")
@@ -344,7 +348,7 @@ def main():
     bench_labels = [lbl for lbl in sections]
     bench_labels.sort()
     for bench_lbl in bench_labels:
-        with open(os.path.join(_script_path(), "benchmarks", "%s.rst" % bench_lbl), 'w') as fd:
+        with open(os.path.join(out_dir, "%s.rst" % bench_lbl), 'w') as fd:
             fd.write(sections[bench_lbl])
             bench_lbl_listing.append(bench_lbl)
 

doc/source/benchmarks.rst

@@ -0,0 +1,11 @@
+==========
+Benchmarks
+==========
+
+Benchpress includes a collection of benchmarks:
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   autodoc_benchmarks/*

doc/source/conf.py

@@ -14,6 +14,7 @@
 
 import sys
 import os
+import pkg_resources
 
 # HACK: we need to run 'autodoc_benchmarks.py' as the first thing
 def _script_path():
@@ -26,7 +27,7 @@ def _script_path():
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-#sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath(os.path.join('..', '..')))
 
 on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
 
@@ -40,11 +41,14 @@ def _script_path():
 # ones.
 extensions = [
     'sphinx.ext.autodoc',
+    'sphinx.ext.napoleon',
     'sphinx.ext.intersphinx',
     'sphinx.ext.todo',
     'sphinx.ext.pngmath',
     'sphinx.ext.ifconfig',
     'sphinx.ext.viewcode',
+    'sphinx.ext.autosummary',
+    'numpydoc',
 ]
 
 todo_include_todos=True
@@ -69,10 +73,13 @@ def _script_path():
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
+
+
+ver_string = pkg_resources.get_distribution("benchpress").version
 # The short X.Y version.
-version = '3.0'
+version = ver_string
 # The full version, including alpha/beta/rc tags.
-release = '3.0'
+release = ver_string
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

doc/source/index.rst

@@ -10,21 +10,13 @@ Contents:
 
 +------------------------------+------------------------------+
 | .. toctree::                 | .. toctree::                 |
-|    :maxdepth: 2              |    :maxdepth: 1              |
-|                              |    :glob:                    |
+|    :maxdepth: 2              |    :maxdepth: 2              |
+|                              |                              |
 |    quickstart                |                              |
 |    install                   |                              |
-|    usage_commands            |    benchmarks/*              |
+|    usage_commands            |    benchmarks                |
 |    usage_examples            |                              |
 |    usage_suites              |                              |
 |    implementing              |                              |
+|    reference/index           |                              |
 +------------------------------+------------------------------+
-
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
-

doc/source/quickstart.rst

@@ -1,7 +1 @@
-Quick Start
-===========
-
-Fire up your terminal, and::
-
-  # Install using PyPi
-  pip install benchpress --user
+.. include:: ../../README.rst

doc/source/reference/benchpress.rst

@@ -0,0 +1,13 @@
+Package
+=======
+
+.. automodule:: benchpress.benchpress
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. automodule:: benchpress.suite_util
+    :members:
+    :undoc-members:
+    :show-inheritance:
+

doc/source/reference/index.rst

@@ -0,0 +1,18 @@
+.. _reference:
+
+#########
+Reference
+#########
+
+:Release: |version|
+:Date: |today|
+
+.. automodule:: benchpress
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. toctree::
+    :maxdepth: 2
+
+    benchpress