development

Development

Relevant source files

• scripts/check_module_size.py
• pyproject.toml
• README.md
• .github/workflows/ci.yml

Local setup

RepoDocs is a Python 3.10+ project managed with uv and built with hatchling. The package has zero runtime dependencies; the only extra is test, which pulls in pytest>=8.

Sources: pyproject.toml:L1-L22

From a clone, run the pipeline against any target repo with uv run:

uv run repodocs-all /path/to/project

This is the local equivalent of the uvx --from repodocs repodocs-all . command documented for end users; running from a clone lets you exercise local source changes instead of the published git ref. The two console entry points, repodocs and repodocs-all, are declared under [project.scripts] and map to repodocs.cli:cli and repodocs.cli:cli_all respectively.

Sources: README.md:L41-L60, pyproject.toml:L17-L19

Running the checks

Run the test suite with the test extra installed:

uv run --extra test pytest -q

Sources: README.md:L178-L181

Lint with ruff, using the project's configured rule set. [tool.ruff] targets Python 3.10 and sets line-length = 120, but line length is not enforced — only pyflakes (F) and the correctness-focused pycodestyle subsets (E4, E7, E9) are selected, on the stated basis that long lines are sometimes deliberate and readable here.

uvx ruff@0.15.22 check .

Sources: pyproject.toml:L43-L50, .github/workflows/ci.yml:L30-L30

Module size guardrail

scripts/check_module_size.py is a CI guardrail script with no dependencies beyond the standard library. It enforces a MAX_LINES = 500 limit on every *.py file under src/repodocs/, on the stated rationale that "no distributed module may grow into an unmaintainable monolith." Files under tests/ are exempt because they are not distributed and may legitimately be longer.

Sources: scripts/check_module_size.py:L1-L11

The offenders() function walks src/repodocs recursively (PKG.rglob("*.py")), counts lines by iterating the file opened in binary mode, and collects (relative_path, line_count) tuples for any file exceeding the limit:

def offenders() -> list[tuple[str, int]]:
    bad = []
    for p in sorted(PKG.rglob("*.py")):
        n = sum(1 for _ in p.open("rb"))
        if n > MAX_LINES:
            bad.append((str(p.relative_to(PKG.parent.parent)), n))
    return bad

main() prints one error line per offending file to stderr and a "split the module before it becomes another monolith" message, exiting 1; with no offenders it prints an "ok" message to stdout and exits 0.

Sources: scripts/check_module_size.py:L14-L35

Run it directly from a clone:

python3 scripts/check_module_size.py

Sources: scripts/check_module_size.py:L34-L35

Continuous integration

.github/workflows/ci.yml runs on every push to main and on pull requests, matrixed across Python 3.10, 3.12, and 3.13 on ubuntu-latest. For each Python version it, in order:

Step	Command
Verify the CLI installs and runs	uvx --from . repodocs --version
Run the test suite	uv run --extra test pytest -q
Lint	uvx ruff@0.15.22 check .
Module size guardrail	python3 scripts/check_module_size.py

The workflow uses astral-sh/setup-uv@v5 for uv provisioning and cancels superseded runs for the same ref via a concurrency group.

Sources: .github/workflows/ci.yml:L1-L31

Version and package layout

The project version is read dynamically from src/repodocs/__init__.py via a VERSION = "..." pattern rather than being hardcoded in pyproject.toml. The wheel and sdist targets both ship src/repodocs and additionally re-include src/repodocs/repo-docs-profile/AGENTS.md as a build artifact, because that path matches the unanchored AGENTS.md .gitignore rule and would otherwise be dropped from packaged distributions — including a wheel built from the sdist rather than directly from a git checkout.

Sources: pyproject.toml:L24-L41

Contributing

Contribution guidelines live in CONTRIBUTING.md; security reporting guidance lives in SECURITY.md.

Sources: README.md:L178-L181