Metadata-Version: 2.4
Name: doctls
Version: 0.1.0
Summary: Technical Documentation Tools
Project-URL: Repository, https://github.com/inventors/doctls
Project-URL: Issues, https://github.com/inventors/doctls/issues
Author: Inventors
License-Expression: MIT
License-File: LICENSE
Keywords: documentation,latex,yaml
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# 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`:

```powershell
uv sync --group dev
```

For an editable install with the active Python interpreter:

```powershell
python -m pip install -e .
```

## CLI Usage

Show the installed package version:

```powershell
doctls --version
```

Expected output:

```text
doctls 0.1.0
```

Show the command help:

```powershell
doctls
```

## Development

Install the development dependencies:

```powershell
uv sync --group dev
```

Run the test suite directly:

```powershell
python -m pytest
```

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

```powershell
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:

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

Run individual tox environments when working on one check:

```powershell
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:

```powershell
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:

```powershell
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:

```powershell
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](docs/release.md).

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:

```powershell
uv run pre-commit run --all-files
```

Validate the requirements verification traceability report:

```powershell
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](docs/automation/phase-runner.md) for prerequisites, commands, outcome handling, logs, and notification sounds.
