[docs] [ci] various improvements to docs building mechanism

* See also legend-exp#240
* Git-ignore API auto-generated docs, run sphinx-apidoc automatically at
  build time
* Cleanup Makefile and conf.py
* add dotfile with python files/dir to ignore when building the API docs
* Update GitHub CI workflow with correct docs dependencies
* Allow for writing documentation in Markdown
* Enforce NumPy style for docstrings

.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/

docs/Makefile

@@ -1,22 +1,26 @@
-SPHINXAPIDOC  ?= sphinx-apidoc
-SPHINXBUILD   ?= sphinx-build
-SPHINXMULTI   ?= sphinx-multiversion
-SOURCEDIR     = source
-BUILDDIRALL   = build/allver/html
-BUILDDIR      = build
+SOURCEDIR = source
+BUILDDIR = build
 
-all: this
-	@$(SPHINXMULTI) "$(SOURCEDIR)" "$(BUILDDIRALL)"
-	cp source/_assets/redirect.html "$(BUILDDIRALL)/index.html"
+# 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)
 
-this:
-	@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+all: apidoc
+	sphinx-build -M html "$(SOURCEDIR)" "$(BUILDDIR)"
+
+allver:
+	sphinx-multiversion "$(SOURCEDIR)" "$(BUILDDIRALL)"
+	cp source/_assets/redirect.html "$(BUILDDIRALL)/index.html"
 
-info:
-	@$(SPHINXMULTI) --dump-metadata "$(SOURCEDIR)" "$(BUILDDIRALL)"
+allver-info:
+	sphinx-multiversion --dump-metadata "$(SOURCEDIR)" "$(BUILDDIRALL)"
 
-regenerate-rst:
-	@$(SPHINXAPIDOC) -f -o $(SOURCEDIR) ../pygama
+apidoc:
+	sphinx-apidoc --module-first --force --output-dir "$(SOURCEDIR)/generated" ../pygama $(PY_SOURCE_EXCLUDE)
 
 clean:
 	rm -rf "$(BUILDDIR)"
+	rm -rf "$(SOURCEDIR)/generated"

docs/source/.py_api_exclude

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

docs/source/conf.py

@@ -1,124 +1,64 @@
 # 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 -------------------------------------------------
-
-# 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
+
+with open(os.path.dirname(__file__) + '/.py_api_exclude') as f:
+    py_exc = f.read().replace('\n', ' ')
+
+# 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 = 'sphinx-apidoc -M -f -o source/generated ../pygama ' + py_exc
 
 # 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
 ==================