doctls 0.1.0

Technical Documentation Tools

doctls

Technical Documentation Tools for documentation projects that combine LaTeX sources with structured input files.

Installation

Create or update the local development environment with uv:

uv sync --group dev

For an editable install with the active Python interpreter:

python -m pip install -e .

CLI Usage

Show the installed package version:

doctls --version

Expected output:

doctls 0.1.0

Show the command help:

doctls

Development

Install the development dependencies:

uv sync --group dev

Run the test suite directly:

python -m pytest

Run the fast local or AI inner-loop checks through tox:

uv run tox

The default tox command runs tests, linting, formatting checks, type checking, and traceability validation. It skips the duplicate coverage run so routine development feedback stays fast.

Run one test file or test function through the tox test environment:

uv run tox -e py -- tests/integration/test_cli_entry_point.py

Run individual tox environments when working on one check:

uv run tox -e py
uv run tox -e coverage
uv run tox -e lint
uv run tox -e format
uv run tox -e type
uv run tox -e traceability

Run the full local validation before final handoff, CI changes, or release work:

uv run tox -e py,coverage,lint,format,type,traceability,build

GitHub Actions runs the same full tox validation on pull requests and pushes to the protected main branch. CI fails when tests fail, coverage drops below the configured threshold, Ruff linting or formatting checks fail, mypy reports type errors, traceability validation fails, or package build and twine check validation fail. The CI workflow only verifies distributable artefacts; it does not upload packages to TestPyPI or PyPI.

Run package build validation directly:

uv run python -m build
uv run twine check dist/*

The build command writes the source distribution and wheel into dist/. Generated build artefacts are ignored by source control.

Run the build validation through tox:

uv run tox -e build

Version metadata is defined in pyproject.toml. Final release versions use semantic versioning in MAJOR.MINOR.PATCH form, for example 0.1.0. Pre-release and release-candidate versions use the corresponding Python package version forms, for example 0.1.0a1, 0.1.0b1, and 0.1.0rc1.

Release and publication procedures, including the pre-publication gate, TestPyPI verification, PyPI API-token credentials, changelog updates, and manual twine upload commands, are documented in Release and Publication.

Future CI and release validation should extend the full validation command instead of replacing the default tox command.

Run pre-commit checks across the repository:

uv run pre-commit run --all-files

Validate the requirements verification traceability report:

uv run python scripts/validate_traceability.py

Package Resources

Runtime resources that must be available from installed packages belong under src/doctls/resources/. Future LaTeX classes, style files, templates, and related assets should be placed in that directory tree.

Package resource inclusion is configured in pyproject.toml with Hatch build includes. Python code should access these files through importlib.resources or the package helper in doctls.resource_access, not by assuming repository file-system paths.

Automation

Phase implementation can be run with the local PowerShell phase runner. See Phase Runner Automation for prerequisites, commands, outcome handling, logs, and notification sounds.