ruff: Enable pydocstyle w/ numpy convention

CHANGES

@@ -19,6 +19,14 @@ $ pipx install --suffix=@next unihan-etl --pip-args '\--pre' --force
 
 <!-- Maintainers, insert changes / features for the next release here -->
 
+### Development
+
+- ci: Add pydocstyle rule to ruff (#303)
+
+### Documentation
+
+- Add docstrings to functions, methods, classes, and packages (#303)
+
 ## unihan-etl 0.29.0 (2023-11-19)
 
 _Maintenance only, no bug fixes, or new features_

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
@@ -24,6 +24,7 @@ def add_doctest_fixtures(
     request: pytest.FixtureRequest,
     doctest_namespace: t.Dict[str, t.Any],
 ) -> None:
+    """Harness pytest fixtures to doctest namespace."""
     if isinstance(request._pyfuncitem, DoctestItem) and shutil.which("tmux"):
         request.getfixturevalue("set_home")
         doctest_namespace["request"] = request
@@ -34,6 +35,7 @@ def set_home(
     monkeypatch: pytest.MonkeyPatch,
     unihan_user_path: pathlib.Path,
 ) -> None:
+    """Set home directory for pytest tests."""
     monkeypatch.setenv("HOME", str(unihan_user_path))
 
 
@@ -44,5 +46,6 @@ def setup(
     unihan_ensure_quick: None,
     unihan_ensure_full: None,
 ) -> None:
+    """Configure test fixtures for pytest."""
     if USING_ZSH:
         request.getfixturevalue("unihan_zshrc")

docs/conf.py

@@ -1,4 +1,5 @@
 # flake8: NOQA: E501
+"""Sphinx configuration for unihan-etl."""
 import inspect
 import pathlib
 import sys
@@ -147,7 +148,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
     -----
@@ -217,11 +218,12 @@ 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"
         tabs_js.unlink(missing_ok=True)
 
 
 def setup(app: "Sphinx") -> None:
-    app.connect("build-finished", remove_tabs_js)
+    """Configure Sphinx app hooks."""

pyproject.toml

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

src/unihan_etl/__about__.py

@@ -1,3 +1,4 @@
+"""Metadata for unihan-etl package."""
 __title__ = "unihan-etl"
 __package_name__ = "unihan_etl"
 __description__ = "Export UNIHAN data of Chinese, Japanese, Korean to CSV, JSON or YAML"

src/unihan_etl/__init__.py

@@ -1 +1,2 @@
+"""Create structured, customized exports of UNIHAN."""
 from .__about__ import __version__

src/unihan_etl/__main__.py

@@ -13,6 +13,7 @@
 
 
 def run() -> "_ExitCode":
+    """Execute unihan-etl via CLI entrypoint."""
     base = pathlib.Path(__file__).parent.parent
     sys.path.insert(0, str(base))
     from .core import Packager

src/unihan_etl/_internal/app_dirs.py

@@ -1,3 +1,19 @@
+"""AppDir wrapper for ``appdirs`` package.
+
+Special features
+----------------
+
+This module offers several advantages over 
+`appdirs <https://github.com/ActiveState/appdirs>`_:
+
+- :mod:`dataclasses`-based object
+- :mod:`pathlib` paths
+- Variable expansion:
+
+  - Environment variables are expanded via :func:`os.path.expandvars`
+  - XDG environmental variables are expanded via :func:`os.path.expandvars`
+  - Tilde expansion is expanded via :func:`os.path.expanduser`
+"""
 import dataclasses
 import os
 import pathlib
@@ -60,6 +76,7 @@ class AppDirs:
     user_log_dir: pathlib.Path = dataclasses.field(default=MISSING_DIR)
 
     def __post_init__(self, _app_dirs: "BaseAppDirs") -> None:
+        """Initialize attributes for AppDirs object."""
         dir_attrs = [key for key in _app_dirs.__dir__() if key.endswith("_dir")]
         dir_mapping: t.Dict[str, str] = {k: getattr(_app_dirs, k) for k in dir_attrs}
         for attr in dir_attrs:

src/unihan_etl/constants.py

@@ -1,4 +1,4 @@
-#: Dictionary of tuples mapping locations of files to fields
+"""Constants for unihan_etl."""
 import importlib.util
 
 from appdirs import AppDirs as BaseAppDirs
@@ -11,6 +11,7 @@
 from unihan_etl.types import ColumnDataTuple
 from unihan_etl.util import get_fields
 
+#: Dictionary of tuples mapping locations of files to fields
 UNIHAN_MANIFEST = {
     "Unihan_DictionaryIndices.txt": (
         "kCheungBauerIndex",

src/unihan_etl/core.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python
-"""Build Unihan into tabular / structured format and export it."""
+"""Download + ETL UNIHAN into structured format and export it."""
 import argparse
 import codecs
 import csv
@@ -79,17 +79,22 @@ def files_exist(path: pathlib.Path, files: t.List[str]) -> bool:
 
 
 class FieldNotFound(Exception):
+    """Raise if field not found in file list."""
+
     def __init__(self, field: str) -> None:
         return super().__init__(f"Field not found in file list: '{field}'")
 
 
 class FileNotSupported(Exception):
+    """Raise if field requested is not included in current file list."""
+
     def __init__(self, field: str) -> None:
         return super().__init__(f"File not supported: '{field}'")
 
 
 #: Return list of files from list of fields.
 def get_files(fields: t.Sequence[str]) -> t.List[str]:
+    """Return list of files required by fields. Simple dependency resolver."""
     files = set()
 
     for field in fields:
@@ -112,7 +117,6 @@ def get_parser() -> argparse.ArgumentParser:
 
     Returns
     -------
-
     :py:class:`argparse.ArgumentParser` :
         argument parser for CLI use.
     """
@@ -428,6 +432,7 @@ def export_csv(
     destination: "StrPath",
     fields: "ColumnData",
 ) -> None:
+    """Export UNIHAN in flattened, CSV format."""
     listified_data = listify(data, fields)
 
     with pathlib.Path(destination).open("w") as f:
@@ -437,12 +442,14 @@ def export_csv(
 
 
 def export_json(data: "UntypedNormalizedData", destination: "StrPath") -> None:
+    """Export UNIHAN in JSON format."""
     with codecs.open(str(destination), "w", encoding="utf-8") as f:
         json.dump(data, f, indent=2, ensure_ascii=False)
         log.info(f"Saved output to: {destination}")
 
 
 def export_yaml(data: "UntypedNormalizedData", destination: "StrPath") -> None:
+    """Export UNIHAN in YAML format."""
     import yaml
 
     with codecs.open(str(destination), "w", encoding="utf-8") as f:
@@ -451,12 +458,14 @@ def export_yaml(data: "UntypedNormalizedData", destination: "StrPath") -> None:
 
 
 def is_default_option(field_name: str, val: t.Any) -> bool:
+    """Return True if option is a unihan-etl default."""
     return bool(val == getattr(DEFAULT_OPTIONS, field_name, ""))
 
 
 def validate_options(
     options: Options,
 ) -> "TypeGuard[Options]":
+    """Validate unihan-etl options."""
     if not is_default_option("input_files", options.input_files) and is_default_option(
         "fields", options.fields
     ):
@@ -485,16 +494,22 @@ def validate_options(
 
 
 class Packager:
-    """Download and generate a tabular release of
-    `UNIHAN <http://www.unicode.org/reports/tr38/>`_."""
+    """Download, ETL, and customize and export of UNIHAN.
+
+    See Also
+    --------
+    - `UNIHAN <http://www.unicode.org/reports/tr38/>`_
+
+    """
 
     options: Options
 
     def __init__(
         self,
         options: t.Union[Options, "t.Mapping[str, t.Any]"] = DEFAULT_OPTIONS,
     ) -> None:
-        """
+        """Initialize UNIHAN Packager.
+
         Parameters
         ----------
         options : dict or Options
@@ -611,7 +626,7 @@ def setup_logger(
     logger: t.Optional[logging.Logger] = None,
     level: "LogLevel" = "DEBUG",
 ) -> None:
-    """Setup logging for CLI use.
+    """Configure logger for CLI use.
 
     Parameters
     ----------