vcs-python · tony · Dec 9, 2023 · Dec 2, 2023 · Dec 9, 2023 · Dec 9, 2023
diff --git a/CHANGES b/CHANGES
@@ -73,13 +73,18 @@ $ 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
 
 - 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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):