Merge pull request #243 from gipert/refactor

Couple of improvements to documentation building and GitHub actions

.github/workflows/main.yml

@@ -58,20 +58,21 @@ jobs:
  python-version: 3.8
  - name: Setup build environment
  run: |
- git fetch --no-tags --prune --no-recurse-submodules --depth=1 origin
+ git fetch --prune --no-recurse-submodules --depth=1 origin
  .github/workflows/get-dependencies.sh
- pip install sphinx sphinx-rtd-theme sphinx-multiversion
+ pip install sphinx sphinx-rtd-theme myst-parser
+ pip install git+https://github.com/samtygier-stfc/sphinx-multiversion.git@prebuild_command
  - name: Build docs for current ref
  run: |
  cd docs
  make clean
- make this
+ make
  - name: Build docs for selected versions (GitHub pages)
  run: |
  cd docs
  make clean
- make info
- make
+ make allver-info
+ make allver
  - if: ${{ github.event_name == 'push' }}
  name: Deploy to GitHub pages
  uses: JamesIves/[email protected]

.gitignore

@@ -80,7 +80,8 @@ instance/
 .scrapy
 
 # Sphinx documentation
-docs/build/
+/docs/build/
+/docs/source/generated
 
 # PyBuilder
 target/
@@ -113,8 +114,5 @@ venv.bak/
 # Rope project settings
 .ropeproject
 
-# mkdocs documentation
-/site
-
 # mypy
 .mypy_cache/

README.md

@@ -1,8 +1,8 @@
 # pygama
 
 ![GitHub tag (latest by date)](https://img.shields.io/github/v/tag/legend-exp/pygama?logo=git)
-![Documentation (master)](https://img.shields.io/badge/documentation-online-purple?logo=readthedocs&link=https%3A%2F%2Flegend-exp.github.io%2Fpygama)
-![GitHub Workflow Status (master)](https://img.shields.io/github/workflow/status/legend-exp/pygama/pygama/master?label=master%20branch&logo=github)
+![Documentation (main)](https://img.shields.io/badge/documentation-online-purple?logo=readthedocs&link=https%3A%2F%2Flegend-exp.github.io%2Fpygama)
+![GitHub Workflow Status (main)](https://img.shields.io/github/workflow/status/legend-exp/pygama/pygama/main?label=main%20branch&logo=github)
 ![GitHub Workflow Status (dev)](https://img.shields.io/github/workflow/status/legend-exp/pygama/pygama/dev?label=dev%20branch&logo=github)
 ![GitHub issues](https://img.shields.io/github/issues/legend-exp/pygama?logo=github)
 ![GitHub pull requests](https://img.shields.io/github/issues-pr/legend-exp/pygama?logo=github)

docs/Makefile

@@ -1,18 +1,28 @@
-SPHINXBUILD ?= sphinx-build
-SPHINXMULTI ?= sphinx-multiversion
-SOURCEDIR = source
-BUILDDIRALL = build/allver/html
-BUILDDIR = build
-
-all: this
- @$(SPHINXMULTI) "$(SOURCEDIR)" "$(BUILDDIRALL)"
+SOURCEDIR = source
+BUILDDIR = build
+
+# docs for all project versions will be placed here
+BUILDDIRALL = $(BUILDDIR)/allver/html
+
+# list in source/.py_api_exclude files or directories that should be excluded
+# from the API auto-generated documentation. No regex allowed
+PY_SOURCE_EXCLUDE = $(shell cat source/.py_api_exclude)
+
+all: apidoc
+ sphinx-build -M html "$(SOURCEDIR)" "$(BUILDDIR)"
+
+allver:
+ sphinx-multiversion "$(SOURCEDIR)" "$(BUILDDIRALL)"
  cp source/_assets/redirect.html "$(BUILDDIRALL)/index.html"
 
-this:
- @$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+allver-info:
+ sphinx-multiversion --dump-metadata "$(SOURCEDIR)" "$(BUILDDIRALL)"
+
+apidoc: clean-apidoc
+ sphinx-apidoc --module-first --force --output-dir "$(SOURCEDIR)/generated" ../pygama $(PY_SOURCE_EXCLUDE)
 
-info:
- @$(SPHINXMULTI) --dump-metadata "$(SOURCEDIR)" "$(BUILDDIRALL)"
+clean-apidoc:
+ rm -rf "$(SOURCEDIR)/generated"
 
-clean:
+clean: clean-apidoc
  rm -rf "$(BUILDDIR)"

docs/source/.py_api_exclude

@@ -0,0 +1 @@
+../pygama/version.py

docs/source/conf.py

@@ -1,124 +1,86 @@
 # 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 pathlib
 import sys
-sys.path.insert(0, os.path.abspath('../..'))
-
-
-# -- Project information -----------------------------------------------------
+import os
+sys.path.insert(0, pathlib.Path(__file__).parents[2].resolve().as_posix())
 
 project = 'pygama'
 copyright = '2020, LEGEND Collaboration'
 
-# -- 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 = [
  'sphinx.ext.githubpages',
- 'sphinx.ext.coverage',
  'sphinx.ext.autodoc',
- 'sphinx.ext.todo',
  'sphinx.ext.mathjax',
- 'sphinx.ext.viewcode',
  'sphinx.ext.napoleon',
  'sphinx_rtd_theme',
- 'sphinx_multiversion'
+ 'sphinx_multiversion',
+ 'myst_parser'
 ]
 
-# The suffix(es) of source filenames.
-# You can specify multiple suffix as a list of string:
-#
-# source_suffix = ['.rst', '.md']
-source_suffix = '.rst'
-
-# The master toctree document.
+source_suffix = {
+ '.rst': 'restructuredtext',
+ '.md': 'markdown',
+}
 master_doc = 'index'
-
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-#
-# This is also used if you do content translation via gettext catalogs.
-# Usually you set "language" from the command line for these cases.
 language = 'python'
-
-# 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 = []
-
-# 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']
-
-# -- Extension configuration -------------------------------------------------
+# list here pygama dependencies that are not required for building docs and
+# could be unmet at build time
+autodoc_mock_imports = [
+ 'pandas',
+ 'numpy',
+ 'matplotlib',
+ 'mplhep',
+ 'scimath',
+ 'numba',
+ 'pytest',
+ 'pyhf',
+ 'awkward',
+ 'iminuit',
+ 'boost-histogram',
+ 'hepunits',
+ 'hepstats',
+ 'uproot',
+ 'h5py',
+ 'pint',
+ 'pyfftw',
+ 'tqdm',
+ 'tinydb',
+ 'parse'
+]
 
-# Napoleon settings
-napoleon_google_docstring = True
+# sphinx-napoleon
+# enforce consistent usage of NumPy-style docstrings
 napoleon_numpy_docstring = True
-napoleon_include_init_with_doc = False
-napoleon_include_private_with_doc = False
-napoleon_include_special_with_doc = True
-napoleon_use_admonition_for_examples = False
-napoleon_use_admonition_for_notes = False
-napoleon_use_admonition_for_references = False
-napoleon_use_ivar = False
-napoleon_use_param = True
-napoleon_use_rtype = True
-
-# -- Options for todo extension ----------------------------------------------
+napoleon_google_docstring = False
 
-# If true, `todo` and `todoList` produce output, else they produce nothing.
-todo_include_todos = True
+# sphinx-autodoc
+# Include __init__() docstring in class docstring
+autoclass_content = 'both'
 
-# -- Options for sphinx-multiversion -----------------------------------------
+# sphinx-multiversion
 
 # For now, we include only (certain) branches when building docs.
 # To add a specific release to the list of versions for which docs should be build,
 # one must create a new branch named `releases/...`
-
-# Whitelist pattern for branches
 smv_branch_whitelist = r'^(main|refactor|releases/.*)$'
-
-# Whitelist pattern for tags
 smv_tag_whitelist = '^$'
-
-# Pattern for released versions
 smv_released_pattern = '^$'
+smv_outputdir_format = '{ref.name}'
+smv_prefer_remote_refs = False
+
+# HACK: we need to regenerate the API documentation before the actual build,
+# but it's not possible with the current sphinx-multiversion. Changes have been
+# proposed in this PR: https://github.com/Holzhaus/sphinx-multiversion/pull/62
+# but there's no timeline for merging yet. For the following option to be considered,
+# one needs to install sphinx-multiversion from a fork with the following:
+# $ pip install git+https://github.com/samtygier-stfc/sphinx-multiversion.git@prebuild_command
+smv_prebuild_command = 'make -ik apidoc'
 
 # The right way to find all docs versions is to look for matching branches on
 # the default remote
-
-# Whitelist pattern for remotes
 smv_remote_whitelist = r'^origin$'
-
-# Format for versioned output directories inside the build directory
-smv_outputdir_format = '{ref.name}'
-
-# Determines whether remote or local git branches/tags are preferred if their output dirs conflict
-smv_prefer_remote_refs = False

docs/source/index.rst

@@ -19,7 +19,7 @@ Package index
  install
  contributing
  tutorials
- Package API reference <pygama>
+ Package API reference <generated/pygama>
 
 Indices and tables
 ==================