ruff: Enable pydocstyle w/ numpy convention (#449)

See also:
- https://www.pydocstyle.org/en/stable/
- https://docs.astral.sh/ruff/settings/#pydocstyle

Author: tony

CHANGES

@@ -29,12 +29,17 @@ $ pip install --user --upgrade --pre libvcs
 
 ### Development
 
+- ci: Add pydocstyle rule to ruff (#449)
 - Add test for direct usage of `HgSync` (#450)
 - pytest-watcher, Add configuration (#450): 
 
   - Run initially by default
   - Skip post-save files from vim
 
+### Documentation
+
+- Add docstrings to functions, methods, classes, and packages (#449)
+
 ## libvcs 0.25.1 (2023-11-23)
 
 ### Packaging

conftest.py

@@ -1,4 +1,4 @@
-"""Conftest.py (root-level)
+"""Conftest.py (root-level).
 
 We keep this in root pytest fixtures in pytest's doctest plugin to be available, as well
 as avoiding conftest.py from being included in the wheel, in addition to pytest_plugin
@@ -20,22 +20,25 @@ def add_doctest_fixtures(
     request: pytest.FixtureRequest,
     doctest_namespace: dict[str, t.Any],
 ) -> None:
+    """Configure doctest fixtures for pytest-doctest."""
     from _pytest.doctest import DoctestItem
 
     if isinstance(request._pyfuncitem, DoctestItem):
         request.getfixturevalue("add_doctest_fixtures")
         request.getfixturevalue("set_home")
 
 
+@pytest.fixture(autouse=True)
+def cwd_default(monkeypatch: pytest.MonkeyPatch, tmp_path: pathlib.Path) -> None:
+    """Configure current directory for pytest tests."""
+    monkeypatch.chdir(tmp_path)
+
+
 @pytest.fixture(autouse=True)
 def setup(
     request: pytest.FixtureRequest,
     gitconfig: pathlib.Path,
     set_home: pathlib.Path,
 ) -> None:
+    """Configure test fixtures for pytest."""
     pass
-
-
-@pytest.fixture(autouse=True)
-def cwd_default(monkeypatch: pytest.MonkeyPatch, tmp_path: pathlib.Path) -> None:
-    monkeypatch.chdir(tmp_path)

docs/conf.py

@@ -1,4 +1,5 @@
 # flake8: NOQA: E501
+"""Sphinx configuration for libvcs."""
 import inspect
 import pathlib
 import sys
@@ -149,7 +150,7 @@
 
 def linkcode_resolve(domain: str, info: dict[str, str]) -> t.Union[None, str]:
     """
-    Determine the URL corresponding to Python object
+    Determine the URL corresponding to Python object.
 
     Notes
     -----
@@ -219,11 +220,13 @@ def linkcode_resolve(domain: str, info: 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"
         tabs_js.unlink(missing_ok=True)
 
 
 def setup(app: "Sphinx") -> None:
+    """Configure Sphinx app hooks."""
     app.connect("build-finished", remove_tabs_js)

pyproject.toml

@@ -147,6 +147,7 @@ select = [
   "TRY", # Trycertatops
   "PERF", # Perflint
   "RUF", # Ruff-specific rules
+  "D", # pydocstyle
 ]
 
 [tool.ruff.isort]
@@ -155,6 +156,9 @@ known-first-party = [
 ]
 combine-as-imports = true
 
+[tool.ruff.pydocstyle]
+convention = "numpy"
+
 [tool.ruff.per-file-ignores]
 "*/__init__.py" = ["F401"]
 

src/libvcs/__about__.py

@@ -1,3 +1,4 @@
+"""Metadata package for libvcs."""
 __title__ = "libvcs"
 __package_name__ = "libvcs"
 __description__ = "Lite, typed, python utilities for Git, SVN, Mercurial, etc."

src/libvcs/_internal/dataclasses.py

@@ -13,19 +13,20 @@
 
 
 class SkipDefaultFieldsReprMixin:
-    r"""Skip default fields in :func:`~dataclasses.dataclass`
-    :func:`object representation <repr()>`.
+    r"""Skip default fields in :func:`~dataclasses.dataclass` object representation.
+
+    See Also
+    --------
+    :func:`object representation <repr()>`
 
     Notes
     -----
-
     Credit: Pietro Oldrati, 2022-05-08, Unilicense
 
     https://stackoverflow.com/a/72161437/1396928
 
     Examples
     --------
-
     >>> @dataclasses.dataclass()
     ... class Item:
     ...     name: str

src/libvcs/_internal/module_loading.py

@@ -56,7 +56,7 @@ def __repr__(self) -> str:
 
 
 def import_string(import_name: str, silent: bool = False) -> t.Any:
-    """Imports an object based on a string.
+    """Import an object based on a string.
 
     This is useful if you want to use import paths as endpoints or
     something similar.  An import path can  be specified either in dotted

src/libvcs/_internal/query_list.py

@@ -14,7 +14,7 @@
 
 
 class MultipleObjectsReturned(Exception):
-    """The requested object does not exist"""
+    """The requested object does not exist."""
 
 
 class ObjectDoesNotExist(Exception):
@@ -132,7 +132,7 @@ def __call__(
         data: t.Union[str, list[str], Mapping[str, str]],
         rhs: t.Union[str, list[str], Mapping[str, str], re.Pattern[str]],
     ) -> bool:
-        """Callback for :class:`QueryList` filtering operators."""
+        """Return callback for :class:`QueryList` filtering operators."""
         ...
 
 

src/libvcs/_internal/run.py

@@ -81,7 +81,7 @@ class ProgressCallbackProtocol(Protocol):
     """Callback to report subprocess communication."""
 
     def __call__(self, output: AnyStr, timestamp: datetime.datetime) -> None:
-        """Callback signature for subprocess communication."""
+        """Process progress for subprocess communication."""
         ...
 
 
@@ -126,7 +126,9 @@ def run(
     check_returncode: bool = True,
     callback: Optional[ProgressCallbackProtocol] = None,
 ) -> str:
-    """Run 'args' in a shell and return the combined contents of stdout and
+    """Run a command.
+
+    Run 'args' in a shell and return the combined contents of stdout and
     stderr (Blocking). Throws an exception if the command exits non-zero.
 
     Keyword arguments are passthrough to :class:`subprocess.Popen`.

src/libvcs/_internal/subprocess.py

@@ -1,4 +1,4 @@
-"""Invocable :mod:`subprocess` wrapper.
+r"""Invocable :mod:`subprocess` wrapper.
 
 Defer running a subprocess, such as by handing to an executor.
 
@@ -8,7 +8,6 @@
 
 Examples
 --------
-
 - :class:`~SubprocessCommand`: Wraps :class:`subprocess.Popen` and
   :func:`subprocess.run` in a :func:`~dataclasses.dataclass`.
 
@@ -19,15 +18,15 @@
   ...    ['echo', 'hi'],
   ...    capture_output=True, universal_newlines=True
   ... ).stdout
-  'hi\\n'
+  'hi\n'
 
   With this:
 
   >>> cmd = SubprocessCommand(['echo', 'hi'])
   >>> cmd.args
   ['echo', 'hi']
   >>> cmd.run(capture_output=True, universal_newlines=True).stdout
-  'hi\\n'
+  'hi\n'
 
   Tweak params before invocation:
 
@@ -36,7 +35,7 @@
   >>> cmd.args
   ['echo', 'hello']
   >>> cmd.run(capture_output=True, universal_newlines=True).stdout
-  'hello\\n'
+  'hello\n'
 """
 import dataclasses
 import subprocess