diff --git a/CHANGES b/CHANGES index d39f592..1850de2 100644 --- a/CHANGES +++ b/CHANGES @@ -73,6 +73,7 @@ $ pipx install --suffix=@next g --pip-args '\--pre' --force - Split out release to separate job so the PyPI Upload docker image isn't pulled on normal runs - Clean up CodeQL +- ci: Add pydocstyle rule to ruff (#18) - Poetry: Bump 1.1.x to 1.2.x ### Packaging @@ -80,6 +81,10 @@ $ pipx install --suffix=@next g --pip-args '\--pre' --force - Remove `.tmuxp-before-script.sh` (was used in `tmuxp.yaml`'s `before_script`) - Drop Python 3.7 (#13) +### Documentation + +- Add docstrings to functions, methods, classes, and packages (#18) + ## g 0.0.2 (2022-09-11) **Maintenance only release, no bug fixes or features** diff --git a/docs/conf.py b/docs/conf.py index c8ee4a0..cd9a0fe 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,4 +1,5 @@ # flake8: noqa: E501 +"""Sphinx configuration for g.""" import contextlib import inspect import pathlib @@ -128,7 +129,7 @@ def linkcode_resolve(domain: str, info: t.Dict[str, str]) -> t.Union[None, str]: """ - Determine the URL corresponding to Python object + Determine the URL corresponding to Python object. Notes ----- @@ -198,6 +199,7 @@ def linkcode_resolve(domain: str, info: t.Dict[str, str]) -> t.Union[None, str]: def remove_tabs_js(app: "Sphinx", exc: Exception) -> None: + """Remove tabs.js from _static after build.""" # Fix for sphinx-inline-tabs#18 if app.builder.format == "html" and not exc: tabs_js = pathlib.Path(app.builder.outdir) / "_static" / "tabs.js" @@ -206,4 +208,5 @@ def remove_tabs_js(app: "Sphinx", exc: Exception) -> None: def setup(app: "Sphinx") -> None: + """Configure Sphinx app hooks.""" app.connect("build-finished", remove_tabs_js) diff --git a/pyproject.toml b/pyproject.toml index c3cc902..cfd07ca 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -109,8 +109,12 @@ select = [ "TRY", # Trycertatops "PERF", # Perflint "RUF", # Ruff-specific rules + "D", # pydocstyle ] +[tool.ruff.pydocstyle] +convention = "numpy" + [tool.ruff.isort] known-first-party = [ "g", diff --git a/src/g/__about__.py b/src/g/__about__.py index a387568..d74cbef 100644 --- a/src/g/__about__.py +++ b/src/g/__about__.py @@ -1,3 +1,4 @@ +"""Metadata package for g.""" __title__ = "g" __package_name__ = "g" __description__ = "cli shortcut for directory's vcs command: git, svn, hg" diff --git a/src/g/__init__.py b/src/g/__init__.py index d913f76..fdd902a 100755 --- a/src/g/__init__.py +++ b/src/g/__init__.py @@ -1,4 +1,5 @@ #!/usr/bin/env python +"""Package for g.""" import pathlib import subprocess import sys @@ -28,6 +29,7 @@ def run( *args: object, **kwargs: t.Any, ) -> t.Optional["subprocess.Popen[str]"]: + """CLI Entrypoint for g, overlay for current directory's VCS utility.""" # Interpret default kwargs lazily for mockability of argv if cmd is DEFAULT: cmd = find_repo_type(pathlib.Path.cwd()) diff --git a/tests/test_cli.py b/tests/test_cli.py index 858edf7..9e3c61c 100644 --- a/tests/test_cli.py +++ b/tests/test_cli.py @@ -1,3 +1,4 @@ +"""Tests for g's CLI package.""" import subprocess import typing as t from unittest.mock import patch @@ -10,6 +11,7 @@ def get_output( *args: t.Any, **kwargs: t.Any ) -> t.Union[subprocess.CalledProcessError, t.Any]: + """Retrieve output from CLI subprocess, whether success or error.""" try: return subprocess.check_output(*args, **kwargs) except subprocess.CalledProcessError as exc: @@ -28,6 +30,7 @@ def test_command_line( argv_args: t.List[str], expect_cmd: str, ) -> None: + """Basic CLI usage.""" from g import sys as gsys with patch.object(gsys, "argv", argv_args):