Development Setup

Python 3.9+

Prepare an editable Doc Gen environment with pytest, Ruff, Black, pre-commit, and packaging tools.

Commandpython -m pip install -e ".[dev]"

Quick Command

create venv -> install dev tools -> enable hooks

editable installpytestRuffBlackpre-commit

Package Python

3.9 or newer

Standard Dev Runtime

Python 3.14

Install Mode

Editable

Optional Helper

GNU Make

Goal

Use an isolated environment whose doc-gen command loads the active checkout. Install .[dev]; a runtime-only editable installation does not include pytest, Ruff, Black, or pre-commit.

Requirements

Python 3.9+

Required

The package supports Python 3.9 or newer; Python 3.14 is the standard development and container runtime.

pip and venv

Required

Install Doc Gen and quality tools into an isolated environment.

Git

Required

Required for source control and the pre-commit hook workflow.

GNU Make

Optional

Provides repeatable setup, QA, Docker, and Compose targets.

Docker

Optional

Required only for container and Compose validation.

Manual Setup

Create and install

bash

python -m venv venv

# Windows PowerShell

venv\Scripts\Activate.ps1

# Linux or macOS

# source venv/bin/activate

python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

Use python -m pip install -e ".[dev,docs]" only when working with the repository's MkDocs source.

Makefile Setup

Setup helpers

bash

make venv
make upgrade-pip
make install-dev

# Combined environment setup and Git-hook installation

make setup

The Make workflow uses the Python interpreter under the conventional venv/ directory.

Pre-Commit Workflow

Doc Gen's hook configuration runs Ruff fixes, Ruff formatting, Black, trailing-whitespace cleanup, and final-newline correction. Ruff and Black read their project policy from pyproject.toml.

Install and run hooks

bash

make pre-commit-install-hooks
make pre-commit-validate
make pre-commit-run-staged
make pre-commit-run

Verify the Environment

Before You Begin

Python is supportedRequired
python --version reports a supported interpreter.
Editable CLI resolvesRequired
doc-gen --help loads from the selected environment.
Quality tools resolveRequired
pytest, Ruff, Black, and pre-commit run through python -m.
Validation uses safe targetsRequired
Use temporary projects and dry-run before live generated-output checks.

Environment check

bash

python --version
python -m pip show doc-gen
doc-gen --help
python -m pytest --version
python -m ruff --version
python -m black --version
python -m pre_commit --version

Related Commands

Commands commonly used together with this command.

Testing

Validate structure and output behavior.

Contributing

Follow Doc Gen's review workflow.

Getting Started

Review end-user setup and first use.

Generate

Understand the writable structure command.

Goal​

Goal