From 393a2a4703908e85c3d95f1bbd80428741d12755 Mon Sep 17 00:00:00 2001 From: Luigi Pertoldi Date: Fri, 25 Mar 2022 12:32:09 +0100 Subject: [PATCH] [docs] [ci] various improvements to docs building mechanism * See also #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 | 11 +- .gitignore | 6 +- docs/Makefile | 30 +++-- docs/source/.py_api_exclude | 1 + docs/source/conf.py | 118 +++++--------------- docs/source/index.rst | 2 +- docs/source/modules.rst | 7 -- docs/source/pygama.analysis.rst | 69 ------------ docs/source/pygama.dsp.rst | 69 ------------ docs/source/pygama.io.rst | 125 --------------------- docs/source/pygama.lh5.rst | 85 -------------- docs/source/pygama.rst | 41 ------- docs/source/pygama.sandbox.rst | 189 -------------------------------- 13 files changed, 58 insertions(+), 695 deletions(-) create mode 100644 docs/source/.py_api_exclude delete mode 100644 docs/source/modules.rst delete mode 100644 docs/source/pygama.analysis.rst delete mode 100644 docs/source/pygama.dsp.rst delete mode 100644 docs/source/pygama.io.rst delete mode 100644 docs/source/pygama.lh5.rst delete mode 100644 docs/source/pygama.rst delete mode 100644 docs/source/pygama.sandbox.rst diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index f449546bd..72d37ba2c 100644 --- a/.github/workflows/main.yml +++ b/.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/github-pages-deploy-action@v4.2.2 diff --git a/.gitignore b/.gitignore index 8f4d45183..be9777d3b 100644 --- a/.gitignore +++ b/.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/ diff --git a/docs/Makefile b/docs/Makefile index 62e24b85c..e9f0f6fc2 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,18 +1,26 @@ -SPHINXBUILD ?= sphinx-build -SPHINXMULTI ?= sphinx-multiversion -SOURCEDIR = source -BUILDDIRALL = build/allver/html -BUILDDIR = build +SOURCEDIR = source +BUILDDIR = build -all: this - @$(SPHINXMULTI) "$(SOURCEDIR)" "$(BUILDDIRALL)" +# 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)" -info: - @$(SPHINXMULTI) --dump-metadata "$(SOURCEDIR)" "$(BUILDDIRALL)" +apidoc: + sphinx-apidoc --module-first --force --output-dir "$(SOURCEDIR)/generated" ../pygama $(PY_SOURCE_EXCLUDE) clean: rm -rf "$(BUILDDIR)" + rm -rf "$(SOURCEDIR)/generated" diff --git a/docs/source/.py_api_exclude b/docs/source/.py_api_exclude new file mode 100644 index 000000000..649b37320 --- /dev/null +++ b/docs/source/.py_api_exclude @@ -0,0 +1 @@ +../pygama/version.py diff --git a/docs/source/conf.py b/docs/source/conf.py index ee2bece0e..c6818e525 100644 --- a/docs/source/conf.py +++ b/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 diff --git a/docs/source/index.rst b/docs/source/index.rst index 71e5696fc..6b5bd296a 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -19,7 +19,7 @@ Package index install contributing tutorials - Package API reference + Package API reference Indices and tables ================== diff --git a/docs/source/modules.rst b/docs/source/modules.rst deleted file mode 100644 index d70389fa7..000000000 --- a/docs/source/modules.rst +++ /dev/null @@ -1,7 +0,0 @@ -pygama -====== - -.. toctree:: - :maxdepth: 4 - - pygama diff --git a/docs/source/pygama.analysis.rst b/docs/source/pygama.analysis.rst deleted file mode 100644 index 215d0f3e8..000000000 --- a/docs/source/pygama.analysis.rst +++ /dev/null @@ -1,69 +0,0 @@ -pygama.analysis package -======================= - -Submodules ----------- - -pygama.analysis.calibration module ----------------------------------- - -.. automodule:: pygama.analysis.calibration - :members: - :undoc-members: - :show-inheritance: - -pygama.analysis.data\_cleaning module -------------------------------------- - -.. automodule:: pygama.analysis.data_cleaning - :members: - :undoc-members: - :show-inheritance: - -pygama.analysis.datagroup module --------------------------------- - -.. automodule:: pygama.analysis.datagroup - :members: - :undoc-members: - :show-inheritance: - -pygama.analysis.histograms module ---------------------------------- - -.. automodule:: pygama.analysis.histograms - :members: - :undoc-members: - :show-inheritance: - -pygama.analysis.metadata module -------------------------------- - -.. automodule:: pygama.analysis.metadata - :members: - :undoc-members: - :show-inheritance: - -pygama.analysis.peak\_fitting module ------------------------------------- - -.. automodule:: pygama.analysis.peak_fitting - :members: - :undoc-members: - :show-inheritance: - -pygama.analysis.pulse\_shape\_analysis module ---------------------------------------------- - -.. automodule:: pygama.analysis.pulse_shape_analysis - :members: - :undoc-members: - :show-inheritance: - -Module contents ---------------- - -.. automodule:: pygama.analysis - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/pygama.dsp.rst b/docs/source/pygama.dsp.rst deleted file mode 100644 index f3c5fa71d..000000000 --- a/docs/source/pygama.dsp.rst +++ /dev/null @@ -1,69 +0,0 @@ -pygama.dsp package -================== - -Submodules ----------- - -pygama.dsp.ProcessingChain module ---------------------------------- - -.. automodule:: pygama.dsp.ProcessingChain - :members: - :undoc-members: - :show-inheritance: - -pygama.dsp.WaveformBrowser module ---------------------------------- - -.. automodule:: pygama.dsp.WaveformBrowser - :members: - :undoc-members: - :show-inheritance: - -pygama.dsp.build\_processing\_chain module ------------------------------------------- - -.. automodule:: pygama.dsp.build_processing_chain - :members: - :undoc-members: - :show-inheritance: - -pygama.dsp.dsp\_optimize module -------------------------------- - -.. automodule:: pygama.dsp.dsp_optimize - :members: - :undoc-members: - :show-inheritance: - -pygama.dsp.errors module ------------------------- - -.. automodule:: pygama.dsp.errors - :members: - :undoc-members: - :show-inheritance: - -pygama.dsp.processors module ----------------------------- - -.. automodule:: pygama.dsp.processors - :members: - :undoc-members: - :show-inheritance: - -pygama.dsp.units module ------------------------ - -.. automodule:: pygama.dsp.units - :members: - :undoc-members: - :show-inheritance: - -Module contents ---------------- - -.. automodule:: pygama.dsp - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/pygama.io.rst b/docs/source/pygama.io.rst deleted file mode 100644 index 611c5ab3d..000000000 --- a/docs/source/pygama.io.rst +++ /dev/null @@ -1,125 +0,0 @@ -pygama.io package -================= - -Submodules ----------- - -pygama.io.MGDODecoder module ----------------------------- - -.. automodule:: pygama.io.MGDODecoder - :members: - :undoc-members: - :show-inheritance: - -pygama.io.ch\_group module --------------------------- - -.. automodule:: pygama.io.ch_group - :members: - :undoc-members: - :show-inheritance: - -pygama.io.compassdaq module ---------------------------- - -.. automodule:: pygama.io.compassdaq - :members: - :undoc-members: - :show-inheritance: - -pygama.io.daq\_to\_raw module ------------------------------ - -.. automodule:: pygama.io.daq_to_raw - :members: - :undoc-members: - :show-inheritance: - -pygama.io.fcdaq module ----------------------- - -.. automodule:: pygama.io.fcdaq - :members: - :undoc-members: - :show-inheritance: - -pygama.io.io\_base module -------------------------- - -.. automodule:: pygama.io.io_base - :members: - :undoc-members: - :show-inheritance: - -pygama.io.lh5 module --------------------- - -.. automodule:: pygama.io.lh5 - :members: - :undoc-members: - :show-inheritance: - -pygama.io.llamadaq module -------------------------- - -.. automodule:: pygama.io.llamadaq - :members: - :undoc-members: - :show-inheritance: - -pygama.io.orca\_digitizers module ---------------------------------- - -.. automodule:: pygama.io.orca_digitizers - :members: - :undoc-members: - :show-inheritance: - -pygama.io.orca\_flashcam module -------------------------------- - -.. automodule:: pygama.io.orca_flashcam - :members: - :undoc-members: - :show-inheritance: - -pygama.io.orcadaq module ------------------------- - -.. automodule:: pygama.io.orcadaq - :members: - :undoc-members: - :show-inheritance: - -pygama.io.pollers module ------------------------- - -.. automodule:: pygama.io.pollers - :members: - :undoc-members: - :show-inheritance: - -pygama.io.raw\_to\_dsp module ------------------------------ - -.. automodule:: pygama.io.raw_to_dsp - :members: - :undoc-members: - :show-inheritance: - -pygama.io.wfcompress module ---------------------------- - -.. automodule:: pygama.io.wfcompress - :members: - :undoc-members: - :show-inheritance: - -Module contents ---------------- - -.. automodule:: pygama.io - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/pygama.lh5.rst b/docs/source/pygama.lh5.rst deleted file mode 100644 index 9973435f2..000000000 --- a/docs/source/pygama.lh5.rst +++ /dev/null @@ -1,85 +0,0 @@ -pygama.lh5 package -================== - -Submodules ----------- - -pygama.lh5.array module ------------------------ - -.. automodule:: pygama.lh5.array - :members: - :undoc-members: - :show-inheritance: - -pygama.lh5.arrayofequalsizedarrays module ------------------------------------------ - -.. automodule:: pygama.lh5.arrayofequalsizedarrays - :members: - :undoc-members: - :show-inheritance: - -pygama.lh5.fixedsizearray module --------------------------------- - -.. automodule:: pygama.lh5.fixedsizearray - :members: - :undoc-members: - :show-inheritance: - -pygama.lh5.lh5\_utils module ----------------------------- - -.. automodule:: pygama.lh5.lh5_utils - :members: - :undoc-members: - :show-inheritance: - -pygama.lh5.scalar module ------------------------- - -.. automodule:: pygama.lh5.scalar - :members: - :undoc-members: - :show-inheritance: - -pygama.lh5.store module ------------------------ - -.. automodule:: pygama.lh5.store - :members: - :undoc-members: - :show-inheritance: - -pygama.lh5.struct module ------------------------- - -.. automodule:: pygama.lh5.struct - :members: - :undoc-members: - :show-inheritance: - -pygama.lh5.table module ------------------------ - -.. automodule:: pygama.lh5.table - :members: - :undoc-members: - :show-inheritance: - -pygama.lh5.vectorofvectors module ---------------------------------- - -.. automodule:: pygama.lh5.vectorofvectors - :members: - :undoc-members: - :show-inheritance: - -Module contents ---------------- - -.. automodule:: pygama.lh5 - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/pygama.rst b/docs/source/pygama.rst deleted file mode 100644 index e04a814db..000000000 --- a/docs/source/pygama.rst +++ /dev/null @@ -1,41 +0,0 @@ -pygama package -============== - -Subpackages ------------ - -.. toctree:: - :maxdepth: 4 - - pygama.analysis - pygama.dsp - pygama.io - pygama.lh5 - pygama.sandbox - -Submodules ----------- - -pygama.utils module -------------------- - -.. automodule:: pygama.utils - :members: - :undoc-members: - :show-inheritance: - -pygama.version module ---------------------- - -.. automodule:: pygama.version - :members: - :undoc-members: - :show-inheritance: - -Module contents ---------------- - -.. automodule:: pygama - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/pygama.sandbox.rst b/docs/source/pygama.sandbox.rst deleted file mode 100644 index 6eaf48781..000000000 --- a/docs/source/pygama.sandbox.rst +++ /dev/null @@ -1,189 +0,0 @@ -pygama.sandbox package -====================== - -Submodules ----------- - -pygama.sandbox.base module --------------------------- - -.. automodule:: pygama.sandbox.base - :members: - :undoc-members: - :show-inheritance: - -pygama.sandbox.base\_calculators module ---------------------------------------- - -.. automodule:: pygama.sandbox.base_calculators - :members: - :undoc-members: - :show-inheritance: - -pygama.sandbox.base\_transforms module --------------------------------------- - -.. automodule:: pygama.sandbox.base_transforms - :members: - :undoc-members: - :show-inheritance: - -pygama.sandbox.compass\_header module -------------------------------------- - -.. automodule:: pygama.sandbox.compass_header - :members: - :undoc-members: - :show-inheritance: - -pygama.sandbox.compass\_wfs module ----------------------------------- - -.. automodule:: pygama.sandbox.compass_wfs - :members: - :undoc-members: - :show-inheritance: - -pygama.sandbox.database module ------------------------------- - -.. automodule:: pygama.sandbox.database - :members: - :undoc-members: - :show-inheritance: - -pygama.sandbox.databases module -------------------------------- - -.. automodule:: pygama.sandbox.databases - :members: - :undoc-members: - :show-inheritance: - -pygama.sandbox.h5parser module ------------------------------- - -.. automodule:: pygama.sandbox.h5parser - :members: - :undoc-members: - :show-inheritance: - -pygama.sandbox.multirun module ------------------------------- - -.. automodule:: pygama.sandbox.multirun - :members: - :undoc-members: - :show-inheritance: - -pygama.sandbox.test module --------------------------- - -.. automodule:: pygama.sandbox.test - :members: - :undoc-members: - :show-inheritance: - -pygama.sandbox.test\_3302 module --------------------------------- - -.. automodule:: pygama.sandbox.test_3302 - :members: - :undoc-members: - :show-inheritance: - -pygama.sandbox.test\_lh5\_buffered\_read module ------------------------------------------------ - -.. automodule:: pygama.sandbox.test_lh5_buffered_read - :members: - :undoc-members: - :show-inheritance: - -pygama.sandbox.test\_pygama module ----------------------------------- - -.. automodule:: pygama.sandbox.test_pygama - :members: - :undoc-members: - :show-inheritance: - -pygama.sandbox.test\_tier\_0 module ------------------------------------ - -.. automodule:: pygama.sandbox.test_tier_0 - :members: - :undoc-members: - :show-inheritance: - -pygama.sandbox.test\_tier\_1 module ------------------------------------ - -.. automodule:: pygama.sandbox.test_tier_1 - :members: - :undoc-members: - :show-inheritance: - -pygama.sandbox.test\_wfc module -------------------------------- - -.. automodule:: pygama.sandbox.test_wfc - :members: - :undoc-members: - :show-inheritance: - -pygama.sandbox.tier1\_base module ---------------------------------- - -.. automodule:: pygama.sandbox.tier1_base - :members: - :undoc-members: - :show-inheritance: - -pygama.sandbox.tier1\_vector module ------------------------------------ - -.. automodule:: pygama.sandbox.tier1_vector - :members: - :undoc-members: - :show-inheritance: - -pygama.sandbox.uproot\_mjd module ---------------------------------- - -.. automodule:: pygama.sandbox.uproot_mjd - :members: - :undoc-members: - :show-inheritance: - -pygama.sandbox.uproot\_test module ----------------------------------- - -.. automodule:: pygama.sandbox.uproot_test - :members: - :undoc-members: - :show-inheritance: - -pygama.sandbox.vec1 module --------------------------- - -.. automodule:: pygama.sandbox.vec1 - :members: - :undoc-members: - :show-inheritance: - -pygama.sandbox.vector module ----------------------------- - -.. automodule:: pygama.sandbox.vector - :members: - :undoc-members: - :show-inheritance: - -Module contents ---------------- - -.. automodule:: pygama.sandbox - :members: - :undoc-members: - :show-inheritance: