DOC: host API documentation for repoma module (#193)

* DOC: add link to `.pre-commit-hooks.yaml`
* DX: recommend MyST VSCode extension
* DX: visualize module dependencies with `pydeps`
  Install graphviz with `conda install graphviz` and run `tox -e pydeps`

.cspell.json

@@ -64,6 +64,7 @@
     "pytest",
     "PYTHONHASHSEED",
     "repoma",
+    "toctree",
     "Zenodo"
   ],
   "ignoreWords": [
@@ -81,6 +82,7 @@
     "indentless",
     "jsonschema",
     "linkcheck",
+    "maxdepth",
     "maxsplit",
     "nargs",
     "nbcell",

.github/workflows/ci.yml

@@ -26,6 +26,14 @@ on:
         type: string
 
 jobs:
+  doc:
+    uses: ComPWA/actions/.github/workflows/ci-docs.yml@v1
+    permissions:
+      pages: write
+      id-token: write
+    with:
+      gh-pages: true
+      specific-pip-packages: ${{ inputs.specific-pip-packages }}
   pytest:
     uses: ComPWA/actions/.github/workflows/pytest.yml@v1
     with:

.gitpod.yml

@@ -18,13 +18,15 @@ vscode:
     - eamodio.gitlens
     - editorconfig.editorconfig
     - esbenp.prettier-vscode
+    - executablebookproject.myst-highlight
     - garaioag.garaio-vscode-unwanted-recommendations
     - github.vscode-github-actions
     - github.vscode-pull-request-github
     - ms-python.black-formatter
     - ms-python.mypy-type-checker
     - ms-python.python
     - ms-python.vscode-pylance
+    - ms-vscode.live-server
     - ms-vsliveshare.vsliveshare
     - redhat.vscode-yaml
     - ryanluker.vscode-coverage-gutters

.vscode/extensions.json

@@ -5,13 +5,15 @@
     "eamodio.gitlens",
     "editorconfig.editorconfig",
     "esbenp.prettier-vscode",
+    "executablebookproject.myst-highlight",
     "garaioag.garaio-vscode-unwanted-recommendations",
     "github.vscode-github-actions",
     "github.vscode-pull-request-github",
     "ms-python.black-formatter",
     "ms-python.mypy-type-checker",
     "ms-python.python",
     "ms-python.vscode-pylance",
+    "ms-vscode.live-server",
     "ms-vsliveshare.vsliveshare",
     "redhat.vscode-yaml",
     "ryanluker.vscode-coverage-gutters",

.vscode/settings.json

@@ -40,6 +40,7 @@
   },
   "git.rebaseWhenSync": true,
   "github-actions.workflows.pinned.workflows": [".github/workflows/ci.yml"],
+  "livePreview.defaultPreviewPath": "docs/_build/html",
   "mypy-type-checker.args": ["--config-file=${workspaceFolder}/pyproject.toml"],
   "mypy-type-checker.importStrategy": "fromEnvironment",
   "python.analysis.autoImportCompletions": false,

README.md

@@ -31,5 +31,10 @@ repos:
       - id: set-nb-cells
 ```
 
-then run `pre-commit autoupdate`. This example lists all available hooks (listed here as
-`id`s) ― you can remove some of them.
+then run
+
+```shell
+pre-commit autoupdate --repo=https://github.com/ComPWA/repo-maintenance
+```
+
+This example lists [all available hooks](./.pre-commit-hooks.yaml) (listed here as `id`s) ― you can remove some of them.

docs/.gitignore

@@ -0,0 +1 @@
+api/

docs/_static/.gitignore

@@ -0,0 +1 @@
+logo.svg

docs/_templates/module.rst_t

@@ -0,0 +1,12 @@
+{%- if show_headings and not separate %}
+{{ basename.split(".")[-1] | e | heading }}
+
+.. code-block:: python
+
+  import {{ basename }}
+
+{% endif -%}
+.. automodule:: {{ qualname }}
+{%- for option in automodule_options %}
+  :{{ option }}:
+{%- endfor %}

docs/_templates/package.rst_t

@@ -0,0 +1,49 @@
+{%- macro automodule(modname, options) -%}
+.. automodule:: {{ modname }}
+{%- for option in options %}
+  :{{ option }}:
+{%- endfor %}
+{%- endmacro %}
+
+{%- macro toctree(docnames) -%}
+.. toctree::
+{% for docname in docnames %}
+  {{ docname }}
+{%- endfor %}
+{%- endmacro %}
+
+{{ pkgname.split(".")[-1] | e | heading }}
+
+.. code-block:: python
+
+  import {{ pkgname }}
+
+{%- if modulefirst and not is_namespace %}
+{{ automodule(pkgname, automodule_options) }}
+{% endif %}
+
+{%- if not modulefirst and not is_namespace %}
+
+{{ automodule(pkgname, automodule_options) }}
+{% endif %}
+
+{%- if submodules or subpackages %}
+.. rubric:: Submodules and Subpackages
+{% endif %}
+
+{%- if subpackages %}
+
+{{ toctree(subpackages) }}
+{% endif %}
+{%- if submodules %}
+{% if separatemodules %}
+{{ toctree(submodules) }}
+{%- else %}
+{%- for submodule in submodules %}
+{% if show_headings %}
+{{- [submodule, "module"] | join(" ") | e | heading(2) }}
+{% endif %}
+{{ automodule(submodule, automodule_options) }}
+{% endfor %}
+{%- endif %}
+{% endif %}

docs/_templates/toc.rst_t

@@ -0,0 +1,7 @@
+{{ header | heading }}
+
+.. toctree::
+  :maxdepth: {{ maxdepth }}
+{% for docname in docnames %}
+  {{ docname }}
+{%- endfor %}

docs/conf.py

@@ -0,0 +1,129 @@
+"""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
+"""
+
+import contextlib
+import os
+import shutil
+import subprocess
+import sys
+from typing import Optional
+
+import requests
+
+if sys.version_info < (3, 8):
+    from importlib_metadata import version as get_package_version
+else:
+    from importlib.metadata import version as get_package_version
+
+
+def fetch_logo(url: str, output_path: str) -> None:
+    if os.path.exists(output_path):
+        return
+    online_content = requests.get(url, allow_redirects=True, timeout=10)
+    with open(output_path, "wb") as stream:
+        stream.write(online_content.content)
+
+
+def generate_api(package: str) -> None:
+    shutil.rmtree("api", ignore_errors=True)
+    subprocess.call(
+        " ".join(
+            [
+                "sphinx-apidoc",
+                f"../src/{package}/",
+                f"../src/{package}/version.py",
+                "-o api/",
+                "--force",
+                "--no-toc",
+                "--templatedir _templates",
+                "--separate",
+            ]
+        ),
+        shell=True,  # noqa: S602
+    )
+
+
+def get_html_logo_path() -> Optional[str]:
+    logo_path = "_static/logo.svg"
+    os.makedirs(os.path.dirname(logo_path), exist_ok=True)
+    with contextlib.suppress(requests.exceptions.ConnectionError):
+        fetch_logo(
+            url="https://raw.githubusercontent.com/ComPWA/ComPWA/04e5199/doc/images/logo.svg",
+            output_path=logo_path,
+        )
+    if os.path.exists(logo_path):
+        return logo_path
+    return None
+
+
+def get_version(package_name: str) -> str:
+    v = get_package_version(package_name)
+    return ".".join(v.split(".")[:3])
+
+
+REPO_NAME = "repo-maintenance"
+PACKAGE_NAME = "repoma"
+generate_api(PACKAGE_NAME)
+
+author = "Common Partial Wave Analysis"
+autodoc_member_order = "bysource"
+autosectionlabel_prefix_document = True
+autodoc_typehints_format = "short"
+copybutton_prompt_is_regexp = True
+copybutton_prompt_text = r">>> |\.\.\. "  # doctest
+copyright = "2023, Common Partial Wave Analysis"  # noqa: A001
+default_role = "py:obj"
+extensions = [
+    "myst_parser",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosectionlabel",
+    "sphinx.ext.doctest",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
+    "sphinx_copybutton",
+]
+html_copy_source = True  # needed for download notebook button
+html_favicon = "_static/favicon.ico"
+html_last_updated_fmt = "%-d %B %Y"
+html_logo = get_html_logo_path()
+html_show_copyright = False
+html_show_sourcelink = False
+html_show_sphinx = False
+html_sourcelink_suffix = ""
+html_static_path = ["_static"]
+html_theme = "sphinx_book_theme"
+html_theme_options = {
+    "logo": {"text": REPO_NAME},
+    "repository_url": f"https://github.com/ComPWA/{REPO_NAME}",
+    "repository_branch": "main",
+    "path_to_docs": "docs",
+    "use_repository_button": True,
+    "show_navbar_depth": 2,
+    "show_toc_level": 2,
+}
+html_title = REPO_NAME
+intersphinx_mapping = {
+    "attrs": ("https://www.attrs.org/en/stable", None),
+    "nbformat": ("https://nbformat.readthedocs.io/en/stable", None),
+    "python": ("https://docs.python.org/3", None),
+    "tomlkit": ("https://tomlkit.readthedocs.io/en/stable", None),
+}
+myst_enable_extensions = [
+    "colon_fence",
+]
+nitpick_ignore = [
+    ("py:class", "repoma.utilities.precommit.T"),
+    ("py:class", "tomlkit.container.Container"),
+]
+nitpick_ignore_regex = [
+    (r"py:.*", r"ruamel\.yaml\..*"),
+]
+nitpicky = True
+primary_domain = "py"
+project = REPO_NAME
+release = get_version(REPO_NAME)
+version = get_version(REPO_NAME)

docs/index.md

@@ -0,0 +1,50 @@
+# ComPWA repo maintenance!
+
+:::{title} Welcome
+:::
+
+This package standardizes and synchronizes the developer environment of repositories by the [ComPWA organization](https://github.com/ComPWA). The maintenance is performed through [pre-commit](https://pre-commit.com) with the use of a number of pre-commit hooks as defined by [`.pre-commit-hooks.yaml`](../.pre-commit-hooks.yaml). The {mod}`check-dev-files <.check_dev_files>` in particular can be used as a **cookie cutter** for new repositories.
+
+## Usage
+
+Add a [`.pre-commit-config.yaml`](https://pre-commit.com/index.html#adding-pre-commit-plugins-to-your-project) file to your repository and list which hooks you want to use:
+
+```yaml
+repos:
+  - repo: https://github.com/ComPWA/repo-maintenance
+    rev: ""
+    hooks:
+      - id: check-dev-files
+        args:
+          - --repo-name="short name for your repository"
+      - id: colab-toc-visible
+      - id: fix-nbformat-version
+      - id: format-setup-cfg
+      - id: pin-nb-requirements
+      - id: set-nb-cells
+```
+
+and install and activate [`pre-commit`](https://pre-commit.com/#install) as follows:
+
+```shell
+pip install pre-commit
+pre-commit autoupdate --repo=https://github.com/ComPWA/repo-maintenance
+pre-commit install
+```
+
+The `repo-maintenance` repository provides the following hooks:
+
+- {mod}`check-dev-files <.check_dev_files>`
+- {mod}`colab-toc-visible <.colab_toc_visible>`
+- {mod}`fix-nbformat-version <.fix_nbformat_version>`
+- {mod}`format-setup-cfg <.format_setup_cfg>`
+- {mod}`pin-nb-requirements <.pin_nb_requirements>`
+- {mod}`set-nb-cells <.set_nb_cells>`
+
+```{toctree}
+:hidden:
+API <api/repoma>
+Changelog <https://github.com/ComPWA/repoma/releases>
+Upcoming features <https://github.com/ComPWA/repoma/milestones?direction=asc&sort=title&state=open>
+Help developing <https://compwa-org.rtfd.io/en/stable/develop.html>
+```

pyproject.toml

@@ -179,6 +179,13 @@ task-tags = ["cspell"]
 known-first-party = ["repoma"]
 
 [tool.ruff.per-file-ignores]
+"docs/*" = [
+    "E402",
+    "INP001",
+    "S101",
+    "S113",
+    "T201",
+]
 "setup.py" = ["D100"]
 "tests/*" = [
     "D",

setup.cfg

@@ -46,6 +46,11 @@ package_dir =
     =src
 
 [options.extras_require]
+doc =
+    myst-parser
+    Sphinx
+    sphinx-book-theme
+    sphinx-copybutton
 test =
     pytest
     pytest-cov
@@ -55,6 +60,7 @@ format =
 mypy =
     mypy
     types-PyYAML
+    types-requests
     types-setuptools
     types-toml
 lint =
@@ -67,9 +73,11 @@ sty =
     %(test)s  # for pytest type hints
     pre-commit >=1.4.0
 dev =
+    %(doc)s
     %(sty)s
     %(test)s
     labels
+    sphinx-autobuild
     tox >=1.9  # for skip_install, use_develop
 
 [options.entry_points]

src/repoma/__init__.py

@@ -1,5 +1,5 @@
 """Bundled developer configurations and tools for ComPWA repositories.
 
-This package contains `pre-commit <https://pre-commit.com>` hooks that the
-`ComPWA repositories <https://github.com/ComPWA>` have in common.
+This package contains `pre-commit <https://pre-commit.com>`_ hooks that the
+`ComPWA repositories <https://github.com/ComPWA>`_ have in common.
 """