DOC: automatically document check-dev-files arguments (#195)

.cspell.json

@@ -70,6 +70,7 @@
   "ignoreWords": [
     "MAINT",
     "PyPI",
+    "argparse",
     "autonumbering",
     "autoupdate",
     "bdist",

docs/check-dev-files.md

@@ -0,0 +1,34 @@
+# `check-dev-files`
+
+This hook is responsible for standardizing and synchronizing the [developer environment](https://compwa-org.rtfd.io/develop.html) of repositories by the [ComPWA organization](https://github.com/ComPWA). Coding conventions are enforced through automated checks instead of through a contribution guide. These conventions have to be regularly updated across all repositories as developer tools introduce new features and deprecate old ones.
+
+The `check-dev-files` hook can also be used as a **cookie cutter** for new repositories by adding the following to your [`.pre-commit-config.yaml`](https://pre-commit.com/index.html#adding-pre-commit-plugins-to-your-project) file:
+
+```yaml
+repos:
+  - repo: https://github.com/ComPWA/repo-maintenance
+    rev: ""
+    hooks:
+      - id: check-dev-files
+        args:
+          - --repo-name="short name for your repository"
+```
+
+and running
+
+```shell
+pre-commit autoupdate --repo=https://github.com/ComPWA/repo-maintenance
+pre-commit run check-dev-files -a
+```
+
+For more implementation details of this hook, check the {mod}`.check_dev_files` module.
+
+## Hook arguments
+
+The `check-dev-files` hook can be configured with by adding any of the following flags to the [`args`](https://pre-commit.com/#config-args) key in your `.pre-commit-config.yaml` file.
+
+```{argparse}
+:module: repoma.check_dev_files
+:func: _create_argparse
+:prog: check-dev-files
+```

docs/conf.py

@@ -85,6 +85,7 @@ def get_version(package_name: str) -> str:
     "sphinx.ext.napoleon",
     "sphinx.ext.viewcode",
     "sphinx_copybutton",
+    "sphinxarg.ext",
 ]
 html_copy_source = True  # needed for download notebook button
 html_favicon = "_static/favicon.ico"

docs/index.md

@@ -3,7 +3,7 @@
 :::{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.
+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 [`check-dev-files`](./check-dev-files.md) in particular can be used as a **cookie cutter** for new repositories.
 
 ## Usage
 
@@ -34,6 +34,7 @@ pre-commit install
 
 The `repo-maintenance` repository provides the following hooks:
 
+- [`check-dev-files`](./check-dev-files.md)
 - {mod}`check-dev-files <.check_dev_files>`
 - {mod}`colab-toc-visible <.colab_toc_visible>`
 - {mod}`fix-nbformat-version <.fix_nbformat_version>`
@@ -43,6 +44,7 @@ The `repo-maintenance` repository provides the following hooks:
 
 ```{toctree}
 :hidden:
+check-dev-files
 API <api/repoma>
 Changelog <https://github.com/ComPWA/repoma/releases>
 Upcoming features <https://github.com/ComPWA/repoma/milestones?direction=asc&sort=title&state=open>

setup.cfg

@@ -49,6 +49,7 @@ package_dir =
 doc =
     myst-parser
     Sphinx
+    sphinx-argparse
     sphinx-book-theme
     sphinx-copybutton
 test =

src/repoma/check_dev_files/__init__.py

@@ -1,7 +1,7 @@
 """A collection of scripts that check the file structure of a repository."""
 
-import argparse
 import sys
+from argparse import ArgumentParser
 from typing import List, Optional, Sequence
 
 from repoma.check_dev_files.deprecated import remove_deprecated_tools
@@ -33,7 +33,56 @@
 
 
 def main(argv: Optional[Sequence[str]] = None) -> int:
-    parser = argparse.ArgumentParser(__doc__)
+    parser = _create_argparse()
+    args = parser.parse_args(argv)
+    is_python_repo = not args.no_python
+    if not args.repo_title:
+        args.repo_title = args.repo_name
+    has_notebooks = not args.no_notebooks
+    executor = Executor()
+    executor(citation.main)
+    executor(commitlint.main)
+    executor(cspell.main)
+    executor(editorconfig.main, args.no_python)
+    if not args.allow_labels:
+        executor(github_labels.main)
+    executor(
+        github_workflows.main,
+        allow_deprecated=args.allow_deprecated_workflows,
+        doc_apt_packages=_to_list(args.doc_apt_packages),
+        no_macos=args.no_macos,
+        no_pypi=args.no_pypi,
+        no_version_branches=args.no_version_branches,
+        single_threaded=args.pytest_single_threaded,
+        skip_tests=_to_list(args.ci_skipped_tests),
+        test_extras=_to_list(args.ci_test_extras),
+    )
+    executor(nbstripout.main)
+    executor(toml.main)  # has to run before pre-commit
+    executor(prettier.main, args.no_prettierrc)
+    if is_python_repo:
+        executor(black.main, has_notebooks)
+        executor(release_drafter.main, args.repo_name, args.repo_title)
+        if args.pin_requirements != "no":
+            executor(
+                update_pip_constraints.main,
+                cron_frequency=args.pin_requirements,
+            )
+        executor(mypy.main)
+        executor(pyright.main)
+        executor(pytest.main)
+        executor(pyupgrade.main)
+        executor(ruff.main)
+        executor(setup_cfg.main, args.ignore_author)
+    executor(remove_deprecated_tools, args.keep_issue_templates)
+    executor(vscode.main, has_notebooks)
+    executor(gitpod.main, args.no_gitpod)
+    executor(precommit.main)
+    return executor.finalize(exception=False)
+
+
+def _create_argparse() -> ArgumentParser:
+    parser = ArgumentParser(__doc__)
     parser.add_argument(
         "--allow-deprecated-workflows",
         action="store_true",
@@ -158,51 +207,7 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
         ),
         type=str,
     )
-    args = parser.parse_args(argv)
-    is_python_repo = not args.no_python
-    if not args.repo_title:
-        args.repo_title = args.repo_name
-    has_notebooks = not args.no_notebooks
-    executor = Executor()
-    executor(citation.main)
-    executor(commitlint.main)
-    executor(cspell.main)
-    executor(editorconfig.main, args.no_python)
-    if not args.allow_labels:
-        executor(github_labels.main)
-    executor(
-        github_workflows.main,
-        allow_deprecated=args.allow_deprecated_workflows,
-        doc_apt_packages=_to_list(args.doc_apt_packages),
-        no_macos=args.no_macos,
-        no_pypi=args.no_pypi,
-        no_version_branches=args.no_version_branches,
-        single_threaded=args.pytest_single_threaded,
-        skip_tests=_to_list(args.ci_skipped_tests),
-        test_extras=_to_list(args.ci_test_extras),
-    )
-    executor(nbstripout.main)
-    executor(toml.main)  # has to run before pre-commit
-    executor(prettier.main, args.no_prettierrc)
-    if is_python_repo:
-        executor(black.main, has_notebooks)
-        executor(release_drafter.main, args.repo_name, args.repo_title)
-        if args.pin_requirements != "no":
-            executor(
-                update_pip_constraints.main,
-                cron_frequency=args.pin_requirements,
-            )
-        executor(mypy.main)
-        executor(pyright.main)
-        executor(pytest.main)
-        executor(pyupgrade.main)
-        executor(ruff.main)
-        executor(setup_cfg.main, args.ignore_author)
-    executor(remove_deprecated_tools, args.keep_issue_templates)
-    executor(vscode.main, has_notebooks)
-    executor(gitpod.main, args.no_gitpod)
-    executor(precommit.main)
-    return executor.finalize(exception=False)
+    return parser
 
 
 def _to_list(arg: str) -> List[str]: