feat: Add Sphinx Documentation

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)
 

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:

docs/source/conf.py

@@ -0,0 +1,100 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# 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.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+from pathlib import Path
+import sys
+
+sys.path.insert(0, str(Path("../src").resolve()))
+sys.path.insert(1, str(Path("./exts").resolve()))
+
+
+def setup(app):
+    app.add_css_file(
+        "https://cdnjs.cloudflare.com/ajax/libs/github-fork-ribbon-css/0.2.2/gh-fork-ribbon.min.css"
+    )
+
+
+# -- Project information -----------------------------------------------------
+
+project = "pyhf-benchmark"
+copyright = "2020, Bo Zheng"
+author = "Bo Zheng"
+
+# The full version, including alpha/beta/rc tags
+release = "0.0.1"
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "m2r2",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.coverage",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.ifconfig",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.githubpages",
+    "sphinxcontrib.bibtex",
+    "sphinx.ext.napoleon",
+    "sphinx_click.ext",
+    "nbsphinx",
+    "sphinx_issues",
+    "sphinx_copybutton",
+    "xref",
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+
+# external links
+xref_links = {"arXiv:1007.1727": ("[1007.1727]", "https://arxiv.org/abs/1007.1727")}
+
+# Github repo
+issues_github_path = "scikit-hep/pyhf/pyhf-benchmark"
+
+# Generate the API documentation when building
+autosummary_generate = True
+numpydoc_show_class_members = False
+
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = "sphinx"
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "sphinx_rtd_theme"
+
+# 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,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ["_static"]
+
+source_suffix = [".rst", ".md"]

docs/source/development.rst

@@ -0,0 +1,58 @@
+Developing
+==========
+
+To develop, we suggest using `virtual environments <https://packaging.python.org/tutorials/installing-packages/#creating-virtual-environments>`__ together with ``pip`` or using `pipenv <https://pipenv.readthedocs.io/en/latest/>`__. Once the environment is activated, clone the repo from GitHub
+
+.. code-block:: console
+
+    git clone https://github.com/pyhf/pyhf-benchmark.git
+
+and install all necessary packages for development
+
+.. code-block:: console
+
+    python -m pip install --ignore-installed -U -e .[complete]
+
+Then setup the Git pre-commit hook for `Black <https://github.com/psf/black>`__  by running
+
+.. code-block:: console
+
+    pre-commit install
+
+Testing
+-------
+
+TestPyPI
+~~~~~~~~
+
+``pyhf-benchmark`` tests packaging and distributing by publishing each commit to
+``master`` to `TestPyPI <https://test.pypi.org/project/pyhf-benchmark/>`__.
+In addition, installation of the latest test release from TestPyPI can be tested
+with
+
+.. code-block:: bash
+
+  python -m pip install --extra-index-url https://test.pypi.org/simple/ --pre pyhf-benchmark
+
+.. note::
+
+  This adds TestPyPI as `an additional package index to search <https://pip.pypa.io/en/stable/reference/pip_install/#cmdoption-extra-index-url>`__
+  when installing ``pyhf-benchmark`` specifically.
+  PyPI will still be the default package index ``pip`` will attempt to install
+  from for all dependencies.
+
+Publishing
+----------
+
+Publishing to `PyPI <https://pypi.org/project/pyhf-benchmark/>`__ and `TestPyPI <https://test.pypi.org/project/pyhf-benchmark/>`__
+is automated through the `PyPA's PyPI publish GitHub Action <https://github.com/pypa/gh-action-pypi-publish>`__
+and the ``pyhf-benchmark`` `Tag Creator GitHub Actions workflow <https://github.com/scikit-hep/pyhf-benchmark/blob/master/.github/workflows/tag.yml>`__.
+A release can be created from any PR created by a core developer by adding a
+``bumpversion`` tag to it that corresponds to the release type:
+`major <https://github.com/scikit-hep/pyhf-benchmark/labels/bumpversion%2Fmajor>`__,
+`minor <https://github.com/scikit-hep/pyhf-benchmark/labels/bumpversion%2Fminor>`__,
+`patch <https://github.com/scikit-hep/pyhf-benchmark/labels/bumpversion%2Fpatch>`__.
+Once the PR is tagged with the label, the GitHub Actions bot will post a comment
+with information on the actions it will take once the PR is merged. When the PR
+has been reviewed, approved, and merged, the Tag Creator workflow will automatically
+create a new release with ``bumpversion`` and then deploy the release to PyPI.

docs/source/examples.rst

@@ -0,0 +1,15 @@
+Examples
+========
+
+Try out in Binder! |Binder|
+
+.. |Binder| image:: https://mybinder.org/badge_logo.svg
+    :target: examples/notebooks/demo.ipynb
+
+Notebooks:
+
+.. toctree::
+   :maxdepth: 2
+   :glob:
+
+   examples/notebooks/*