From 07b4664fe03b3664d344349ba80ba88bf66470e6 Mon Sep 17 00:00:00 2001 From: Remco de Boer <29308176+redeboer@users.noreply.github.com> Date: Fri, 6 Oct 2023 14:30:16 +0200 Subject: [PATCH] DOC: automatically document `check-dev-files` arguments --- .cspell.json | 1 + docs/check-dev-files.md | 34 +++++++++ docs/conf.py | 1 + docs/index.md | 4 +- setup.cfg | 1 + src/repoma/check_dev_files/__init__.py | 99 ++++++++++++++------------ 6 files changed, 92 insertions(+), 48 deletions(-) create mode 100644 docs/check-dev-files.md diff --git a/.cspell.json b/.cspell.json index 808adae3..e90954d5 100644 --- a/.cspell.json +++ b/.cspell.json @@ -70,6 +70,7 @@ "ignoreWords": [ "MAINT", "PyPI", + "argparse", "autonumbering", "autoupdate", "bdist", diff --git a/docs/check-dev-files.md b/docs/check-dev-files.md new file mode 100644 index 00000000..cb329716 --- /dev/null +++ b/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 +``` diff --git a/docs/conf.py b/docs/conf.py index 63960ac5..6312c370 100644 --- a/docs/conf.py +++ b/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" diff --git a/docs/index.md b/docs/index.md index 0303c71c..e7cedd93 100644 --- a/docs/index.md +++ b/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 Changelog Upcoming features diff --git a/setup.cfg b/setup.cfg index dc024360..4419d7e2 100644 --- a/setup.cfg +++ b/setup.cfg @@ -49,6 +49,7 @@ package_dir = doc = myst-parser Sphinx + sphinx-argparse sphinx-book-theme sphinx-copybutton test = diff --git a/src/repoma/check_dev_files/__init__.py b/src/repoma/check_dev_files/__init__.py index cefd0367..f5bfb8c0 100644 --- a/src/repoma/check_dev_files/__init__.py +++ b/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]: