Python docs

Skill bitwise-media-group/skills/plugins/python/skills/python-docs

Coding agent marketplace for skills used by the BitWise Media Group.

Install

npx -y skills add bitwise-media-group/skills --skill python-docs

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Python documentation conventions — a Google-style docstring on every public module, class, and function, enforced by ruff's pydocstyle (D) rules with the google convention, and LLM-ready markdown CLI reference generation for Click or Typer tools via a reproducible docgen helper. Use when writing or reviewing docstrings, choosing or enforcing a docstring style, configuring ruff's D rules, deciding where module or package docstrings belong, or generating markdown CLI documentation for a Click/Typer-based Python tool.

The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

3.4 KB, as published. Nobody here has run it

Python documentation conventions

Docstrings are the API's reference manual: editors, help(), and doc generators render them, and LLM coding agents read them to learn an API. These rules say where they go, what style they take, and how the linter enforces them. For the code itself see the python-style skill.

1. A docstring on every public API, Google style

Every public module, class, function, and method carries a docstring; private (_-prefixed) and trivial dunder methods do not need one. Use Google style — a one-line imperative summary, then Args:, Returns:, Raises: as needed:

def parse(line: str) -> tuple[str, str]:
    """Split a KEY=VALUE line into its key and value.

    Args:
        line: A single ``key=value`` pair; whitespace around each side is trimmed.

    Returns:
        The ``(key, value)`` pair.

    Raises:
        ValueError: If the separator is missing or the key is empty.
    """

Document behavior and invariants the caller can rely on, not the implementation. Types live in the annotations (see python-typing), so do not repeat them in the docstring prose.

2. Module and package docstrings

Every module starts with a docstring on line 1 (after from __future__ import annotations if present) describing what it provides. A package's docstring lives in its __init__.py.

3. Enforce with ruff's D rules

Make docstring presence and format a lint error, not a review nit — add the D family and pin the convention so ruff checks Google style specifically:

[tool.ruff.lint]
extend-select = ["D"]

[tool.ruff.lint.pydocstyle]
convention = "google"

[tool.ruff.lint.per-file-ignores]
"tests/**" = ["D"]   # tests document themselves through their names

uv run ruff check now flags missing and malformed docstrings.

4. Generate an LLM-ready CLI reference

A Click command tree (Typer compiles to Click) already knows every command, flag, and help string — publish it as one markdown page per command that humans, search engines, and LLMs can read:

Give every command and option a clear help string; expose the root command from your CLI module.
Copy templates/docgen.py to src/myapp/tools/docgen.py and point its import at your command (for Typer, convert with typer.main.get_command(app)). It walks the tree writing timestamp-free markdown, so the output is reproducible.

It imports your application packages, so it runs in-project with uv run — it is not a separate tool. Add a Makefile target:

docs: ## Regenerate the CLI reference (docs/cli) from the command tree
	uv run python -m myapp.tools.docgen --out docs/cli

Commit the generated docs/cli and refresh it whenever commands or flags change, so the reference never drifts from the tool.

For style see the python-style skill; for the Makefile and layout see python-project.