docs: basic Sphinx setup (#30)

* basic sphinx documentation setup

.gitignore

@@ -21,3 +21,6 @@ build
 *.npy
 *.npz
 *.json
+
+# sphinx
+docs/_build

README.md

@@ -50,7 +50,7 @@ To run the following example, first generate the input files via the script `uti
 ```python
 import cabinetry
 
-cabinetry_config = cabinetry.config.read("config_example.yml")
+cabinetry_config = cabinetry.configuration.read("config_example.yml")
 
 # create template histograms
 histo_folder = "histograms/"

docs/api.rst

@@ -0,0 +1,67 @@
+API
+=========
+
+.. contents::
+    :local:
+    :backlinks: none
+
+
+cabinetry.configuration
+-----------------------
+
+.. automodule:: cabinetry.configuration
+   :members:
+
+
+cabinetry.fit
+-------------
+
+.. automodule:: cabinetry.fit
+   :members:
+
+
+cabinetry.histo
+---------------
+
+.. automodule:: cabinetry.histo
+   :members:
+
+
+cabinetry.template_builder
+--------------------------
+
+.. automodule:: cabinetry.template_builder
+   :members:
+
+
+cabinetry.template_postprocessor
+--------------------------------
+
+.. automodule:: cabinetry.template_postprocessor
+   :members:
+
+
+cabinetry.visualize
+-------------------
+
+.. automodule:: cabinetry.visualize
+   :members:
+
+
+cabinetry.workspace
+-------------------
+
+.. automodule:: cabinetry.workspace
+   :members:
+
+
+cabinetry.contrib
+-----------------
+
+.. automodule:: cabinetry.contrib
+
+.. automodule:: cabinetry.contrib.histogram_creation
+   :members:
+
+.. automodule:: cabinetry.contrib.histogram_drawing
+   :members:

docs/conf.py

@@ -0,0 +1,12 @@
+project = "cabinetry"
+author = "cabinetry developers"
+copyright = f"2020, {author}"
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx_rtd_theme",
+]
+
+import sphinx_rtd_theme
+
+html_theme = "sphinx_rtd_theme"

docs/index.rst

@@ -0,0 +1,56 @@
+`cabinetry`
+==============================
+
+.. toctree::
+   :hidden:
+   :maxdepth: 1
+
+
+   api
+   license
+
+`cabinetry` is a tool to build and steer (profile likelihood) template fits with applications in high energy physics in mind.
+It acts as an interface to many powerful tools to make it easier for an analyzer to run their statistical inference pipeline.
+
+This documentation can be built and viewed via
+
+.. code-block:: bash
+
+   sphinx-build docs docs/_build
+   open docs/_build/index.html
+
+Hello world
+-----------
+
+.. code-block:: python
+
+   import cabinetry
+
+   cabinetry_config = cabinetry.configuration.read("config_example.yml")
+
+   # create template histograms
+   histo_folder = "histograms/"
+   cabinetry.template_builder.create_histograms(
+       cabinetry_config, histo_folder, method="uproot"
+   )
+
+   # perform histogram post-processing
+   cabinetry.template_postprocessor.run(cabinetry_config, histo_folder)
+
+   # visualize templates and data
+   cabinetry.visualize.data_MC(
+       cabinetry_config, histo_folder, "figures/", prefit=True, method="matplotlib"
+   )
+
+   # build a workspace
+   ws = cabinetry.workspace.build(cabinetry_config, histo_folder)
+
+   # run a fit
+   cabinetry.fit.fit(ws)
+
+The above is an abbreviated version of an example included in `example.py`, which shows how to use `cabinetry`.
+Beyond the core dependencies of `cabinetry` (currently `pyyaml`, `numpy`, `pyhf`, `iminuit`), it also requires additional libraries: `uproot`, `scipy`, `matplotlib`, `numexpr`.
+
+Acknowledgements
+----------------
+This work was supported by the U.S. National Science Foundation (NSF) cooperative agreement OAC-1836650 (IRIS-HEP).

docs/license.rst

@@ -0,0 +1,4 @@
+License
+=======
+
+.. include:: ../LICENSE