feat: Add Sphinx Documentation

.github/workflows/ci.yml

@@ -43,3 +43,40 @@ jobs:
         token: ${{ secrets.CODECOV_TOKEN }}
         file: ./coverage.xml
         flags: unittests
+
+  docs:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [3.8]
+
+    steps:
+    - uses: actions/checkout@v2
+      with:
+        fetch-depth: 0
+    - name: Set up Python 3.8
+      uses: actions/setup-python@v2
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip setuptools wheel
+        python -m pip install -q --no-cache-dir --use-feature=2020-resolver -e .[docs]
+        python -m pip list
+        sudo apt-get update
+        sudo apt-get -qq install pandoc
+    - name: Test and build docs
+      run: |
+        python setup.py build_sphinx
+        touch docs/_build/html/.nojekyll
+    - name: Deploy docs to GitHub Pages
+      if: success() && github.event_name == 'push' && github.ref == 'refs/heads/master'
+      uses: peaceiris/actions-gh-pages@v3
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: docs/_build/html
+        force_orphan: true
+        user_name: 'github-actions[bot]'
+        user_email: 'github-actions[bot]@users.noreply.github.com'
+        commit_message: Deploy to GitHub pages

README.md

@@ -56,7 +56,7 @@ Options:
 
 ## Authors
 
-`pyhf-benchmark` is openly developed by [Bo Zheng](https://iris-hep.org/fellows/BoZheng.html) and the [`pyhf` dev team](https://scikit-hep.org/pyhf/#authors).
+`pyhf-benchmark` is openly developed by [Bo Zheng](https://iris-hep.org/fellows/BoZheng.html) and the [pyhf dev team](https://scikit-hep.org/pyhf/#authors).
 
 Please check the [contribution statistics for a list of contributors.](https://github.com/pyhf/pyhf-benchmark/graphs/contributors)
 

README.rst

@@ -0,0 +1,82 @@
+pyhf-benchmark
+==============
+
+|GitHub Project| |GitHub Actions Status: CI| |Code Coverage| |Code
+style: black|
+
+Benchmarking of hardware acceleration of ``pyhf``
+
+Environment
+-----------
+
+For the time being, until a library can be created, use the
+``requirements.txt`` to also serve setup duty in your virtual
+environment in addition to providing a reproducible benchmarking
+environment.
+
+::
+
+    (pyhf-benchmark) $ python -m pip install -r requirements.txt
+
+Usage
+-----
+
+::
+
+    $ pyhf-benchmark run --help
+    Usage: pyhf-benchmark run [OPTIONS]
+
+        Automatic process of taking pyhf computation.
+
+        Usage:
+
+        $ pyhf-benchmark run -c [-b] [-p] [-u] [-m] [-n] [-mm]
+
+      Examples:
+
+        $ pyhf-benchmark run -c mle -b numpy -u https://www.hepdata.net/record/resource/1267798?view=true -m [750,100] |
+        $ pyhf-benchmark run -c mle -u https://www.hepdata.net/record/resource/1267798?view=true -m [750,100] |
+        $ pyhf-benchmark run -c mle -b numpy -p 1Lbb-likelihoods-hepdata -m [750,100] |
+        $ pyhf-benchmark run -c interpolation -b jax -n 0 -mm fast |
+        $ pyhf-benchmark run -c interpolation -b numpy -n 0 -mm slow |
+
+      More information:
+
+        https://github.com/pyhf/pyhf-benchmark
+
+
+
+    Options:
+      -c, -computation TEXT   Type of computation  [required]
+      -b, --backend TEXT      Name of the pyhf backend to run with.
+      -p, --path TEXT         Local path of workspace.
+      -u, --url TEXT          Online data link.
+      -m, --model-point TEXT  Model point.
+      -n, --number TEXT       Number.
+      -mm, --mode TEXT        Mode.
+      -h, --help              Show this message and exit.
+
+Authors
+-------
+
+``pyhf-benchmark`` is openly developed by `Bo
+Zheng <https://iris-hep.org/fellows/BoZheng.html>`__ and the `pyhf dev
+team <https://scikit-hep.org/pyhf/#authors>`__.
+
+Please check the `contribution statistics for a list of
+contributors. <https://github.com/pyhf/pyhf-benchmark/graphs/contributors>`__
+
+Acknowledgements
+----------------
+
+Bo Zheng was awarded an `IRIS-HEP
+Fellowship <https://iris-hep.org/fellows/BoZheng.html>`__ for this work.
+
+.. |GitHub Project| image:: https://img.shields.io/badge/GitHub--blue?style=social&logo=GitHub
+   :target: https://github.com/pyhf/pyhf-benchmark
+.. |GitHub Actions Status: CI| image:: https://github.com/pyhf/pyhf-benchmark/workflows/CI/badge.svg?branch=master
+   :target: https://github.com/pyhf/pyhf-benchmark/actions?query=workflow%3ACI+branch%3Amaster
+.. |Code Coverage| image:: https://codecov.io/gh/pyhf/pyhf-benchmark/graph/badge.svg?branch=master
+   :target: https://codecov.io/gh/pyhf/pyhf-benchmark?branch=master
+.. |Code style: black| image:: https://img.shields.io/badge/code%20style-black-000000.svg
+   :target: https://github.com/psf/black

docs/.ackrc

@@ -0,0 +1 @@
+--ignore-directory=docs/_generated

docs/Makefile

@@ -0,0 +1,25 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+GENERATEDDIR  = _generated
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: clean
+clean:
+	rm -rf $(GENERATEDDIR)/*

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/source/_templates/modifierclass.rst

@@ -0,0 +1,30 @@
+:github_url: https://github.com/pyhf/pyhf-benchmark/blob/master/{{module | replace(".", "/") }}
+
+{{ name | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ name }}
+   :show-inheritance:
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: Attributes
+
+   {% for item in attributes %}
+   .. autoattribute:: {{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block methods %}
+   {% if methods %}
+   .. rubric:: Methods
+
+   {% for item in methods %}
+   {% if item not in inherited_members %}
+   .. automethod:: {{ name }}.{{ item }}
+   {% endif %}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}

docs/source/api.rst

@@ -0,0 +1,98 @@
+Python API
+==========
+
+Run
+-----------------------------------------
+
+.. currentmodule:: pyhf_benchmark.run
+
+.. autosummary::
+   :toctree: _generated/
+
+    run
+
+Load
+-----------------------------------------
+
+.. currentmodule:: pyhf_benchmark.load
+
+.. autosummary::
+   :toctree: _generated/
+
+   download
+   open_local_file
+   delete_downloaded_file
+
+Maximum Likelihood Computation
+-----------------------------------------
+
+.. currentmodule:: pyhf_benchmark.mle
+
+.. autosummary::
+   :toctree: _generated/
+
+   get_bkg_and_signal
+   calculate_CLs
+
+Plot
+--------
+
+.. currentmodule:: pyhf_benchmark.plot
+
+.. autosummary::
+   :toctree: _generated/
+
+   load
+   load_all
+   plot
+   subplot
+   plot_comb
+   subplot_comb
+
+Manager
+----------
+
+.. currentmodule:: pyhf_benchmark.manager
+
+.. autosummary::
+   :toctree: _generated/
+   :nosignatures:
+   :template: modifierclass.rst
+
+   RunManager
+
+SystemStats
+-------------
+
+.. currentmodule:: pyhf_benchmark.stats
+
+.. autosummary::
+   :toctree: _generated/
+   :nosignatures:
+   :template: modifierclass.rst
+
+   SystemStats
+   gpu_in_use_by_this_process
+
+JsonlEventsFile
+-----------------
+
+.. currentmodule:: pyhf_benchmark.jsonlfile
+
+.. autosummary::
+   :toctree: _generated/
+   :nosignatures:
+   :template: modifierclass.rst
+
+   JsonlEventsFile
+
+
+Utilities
+---------
+
+.. currentmodule:: pyhf_benchmark.util
+
+.. autosummary::
+   :toctree: _generated/
+
+   random_histosets_alphasets_pair

docs/source/cli.rst

@@ -0,0 +1,6 @@
+Command Line API
+================
+
+.. click:: pyhf_benchmark.cli.cli:pyhf_benchmark
+   :prog: pyhf_benchmark
+   :show-nested: