fix: adjust tons of doc links to actually work

Author: 56kyle

docs/our-chosen-toolchain.md

@@ -97,13 +97,13 @@ Here is the breakdown of the chosen tool(s) for each defined area:
 
 The true power of this template lies in how these chosen tools work together cohesively. The workflow centers around:
 
-1.  **Configuration:** Defined primarily in `pyproject.toml` and separate tool config files ([01](#area-01-project-structure-and-basic-setup)).
-2.  **Dependency/Environment Management:** Handled efficiently by [:term:`uv`](uv-documentation), creating standard virtual environments and managing packages based on `pyproject.toml` and `uv.lock` ([02](#area-02-dependency-management)).
-3.  **Task Automation:** Orchestrated by [:term:`Nox`](nox-documentation), calling commands from other tools via `uv run` (or `uvx`), providing the single interface for developers and CI/CD to run workflows ([12](#area-12-task-automation-developer-workflow)).
-4.  **Code Quality & Testing:** Ensured by [:term:`Ruff`](ruff-documentation) (formatting/linting), [:term:`Pyright`](pyright-documentation) (typing), [:term:`pip-audit`](pip-audit-documentation) (dep security), and [:term:`Bandit`](bandit-bandit-documentation) (code security), along with [:term:`pytest`](pytest-pytest-cov-documentation)/[:term:`coverage.py`](coveragepy-coverage-documentation) for testing. These tools are installed via [:term:`uv`](uv-documentation) and executed via Task Automation ([03](#area-03-code-formatting)-[08](#area-08-code-security-and-safety-checks), orchestrated by [12](#area-12-task-automation-developer-workflow)).
-5.  **Packaging & Distribution:** Artifacts created via [:term:`uv`](uv-documentation) build using selected backends, and published via [:term:`uv`](uv-documentation) publish, orchestrated by Task Automation ([09](#area-09-packaging-build)-[10](#area-10-package-publishing-to-pypiindex-servers)).
-6.  **Containerization:** Defined by `Dockerfile`, built by [:term:`Docker`](docker-documentation)/[:term:`Podman`](podman-documentation) (often via `uv` installing deps inside), orchestrated by Task Automation. Local multi-container setups managed by [:term:`Docker Compose`](docker-documentation) ([11](#area-11-application-container-building), [15](#area-15-container-orchestration-local-single-host)).
-7.  **Automated Workflows:** Triggered by CI/CD platforms (configured to call Task Automation commands), handling matrices, secrets, and reporting ([13](#area-13-continuous-integration-ci-orchestration)-[14](#area-14-continuous-deployment-delivery-cd-orchestration)).
-8.  **Development Environment:** Consistent locally ([:term:`uv`](uv-documentation) venvs, [:term:`pre-commit`](pre-commit-documentation)) and reproducibly within a container via Dev Containers ([17](#area-17-containerized-development-environments)), simplifying setup and ensuring uniformity.
+1.  **Configuration:** Defined primarily in `pyproject.toml` and separate tool config files ([01](topics/01_project-structure.md)).
+2.  **Dependency/Environment Management:** Handled efficiently by [:term:`uv`](uv-documentation), creating standard virtual environments and managing packages based on `pyproject.toml` and `uv.lock` ([02](topics/02_dependency-management.md)).
+3.  **Task Automation:** Orchestrated by [:term:`Nox`](nox-documentation), calling commands from other tools via `uv run` (or `uvx`), providing the single interface for developers and CI/CD to run workflows ([12](topics/12_task-automation.md)).
+4.  **Code Quality & Testing:** Ensured by [:term:`Ruff`](ruff-documentation) (formatting/linting), [:term:`Pyright`](pyright-documentation) (typing), [:term:`pip-audit`](pip-audit-documentation) (dep security), and [:term:`Bandit`](bandit-bandit-documentation) (code security), along with [:term:`pytest`](pytest-pytest-cov-documentation)/[:term:`coverage.py`](coveragepy-coverage-documentation) for testing. These tools are installed via [:term:`uv`](uv-documentation) and executed via Task Automation ([03](topics/03_code-formatting.md)-[08](topics/08_security-checks.md), orchestrated by [12](topics/12_task-automation.md)).
+5.  **Packaging & Distribution:** Artifacts created via [:term:`uv`](uv-documentation) build using selected backends, and published via [:term:`uv`](uv-documentation) publish, orchestrated by Task Automation ([09](topics/09_packaging-build.md)-[10](topics/10_packaging-publish.md)).
+6.  **Containerization:** Defined by `Dockerfile`, built by [:term:`Docker`](docker-documentation)/[:term:`Podman`](podman-documentation) (often via `uv` installing deps inside), orchestrated by Task Automation. Local multi-container setups managed by [:term:`Docker Compose`](docker-documentation) ([11](topics/11_container-build.md), [15](topics/15_compose-local.md)).
+7.  **Automated Workflows:** Triggered by CI/CD platforms (configured to call Task Automation commands), handling matrices, secrets, and reporting ([13](topics/13_ci-orchestration.md)-[14](topics/14_cd-orchestration.md)).
+8.  **Development Environment:** Consistent locally ([:term:`uv`](uv-documentation) venvs, [:term:`pre-commit`](pre-commit-documentation)) and reproducibly within a container via Dev Containers ([17](topics/17_dev-containers.md)), simplifying setup and ensuring uniformity.
 
 By choosing `cookiecutter-robust-python`, users gain this pre-configured, integrated, and documented workflow, allowing them to focus on building their application with a strong, modern, and robust foundation.

docs/topics/02_dependency_management.md docs/topics/02_dependency-management.mddocs/topics/02_dependency_management.md renamed to docs/topics/02_dependency-management.md

@@ -26,14 +26,14 @@ This section evaluates different tools and approaches for managing project depen
 
 We evaluated the most prominent options for managing Python project dependencies:
 
-### Option 1: [:py:mod:`pip`](pip-documentation) + [:term:`venv`](python:venv-tutorial) / [:term:`virtualenv`](virtualenv-documentation) (+ [:term:`pip-tools`](pip-tools-documentation))
+### Option 1: [pip](pip-documentation) + [:term:`venv`](python:venv-tutorial) / [:term:`virtualenv`](virtualenv-documentation) (+ [:term:`pip-tools`](pip-tools-documentation))
 
 *   **Description:** The traditional standard using `pip` for installation within isolated virtual environments created by `venv` (stdlib) or `virtualenv`. `pip-tools` (`pip-compile`, `pip-sync`) is often added to manage dependencies via `requirements.in` and generate reproducible `requirements.txt` lock files.
 *   **Evaluation:**
-    *   **PEP Compliance:** Moderate. [:py:mod:`pip`](pip-documentation) understands PEP 621 for installing from `pyproject.toml`. [:term:`pip-tools`](pip-tools-documentation) can read from `pyproject.toml`. No native support for standard lock file formats (PEP 665), relies on generated `requirements.txt` which is a common convention but lacks richer metadata.
+    *   **PEP Compliance:** Moderate. [pip](pip-documentation) understands PEP 621 for installing from `pyproject.toml`. [:term:`pip-tools`](pip-tools-documentation) can read from `pyproject.toml`. No native support for standard lock file formats (PEP 665), relies on generated `requirements.txt` which is a common convention but lacks richer metadata.
     *   **Reproducibility:** High *with `pip-tools`*. `requirements.txt` generated by `pip-tools` provides strong pinning. Pure `pip` relies on `pip freeze` which is less deterministic.
     *   **OS Interoperability:** Excellent. Core tools are foundational Python utilities robust across OSs. [:term:`pip-tools`](pip-tools-documentation) is pure Python and cross-platform.
-    *   **Performance:** Moderate. [:py:mod:`pip`](pip-documentation)'s dependency resolver can be slow for large/complex graphs. `pip-compile` adds time. [:term:`venv`](python:venv-tutorial)/[:term:`virtualenv`](virtualenv-documentation) creation/activation faster than some, slower than others (like uv).
+    *   **Performance:** Moderate. [pip](pip-documentation)'s dependency resolver can be slow for large/complex graphs. `pip-compile` adds time. [:term:`venv`](python:venv-tutorial)/[:term:`virtualenv`](virtualenv-documentation) creation/activation faster than some, slower than others (like uv).
     *   **Developer Experience (DX):** Moderate. Requires multi-step workflow: create env, activate, manually edit requirement files, run `pip-compile`, run `pip-sync`/`pip install -r`. No single command for `add` or `remove`.
     *   **Dependency Group Management:** Achieved by manually managing multiple `.in` / `.txt` files or leveraging `[project.optional-dependencies]` via `pip-tools`, less integrated than other tools.
     *   **Integration:** Excellent. As the standard, most ecosystem tools inherently understand [:term:`venv`](python:venv-tutorial)s, `pip install`, and `requirements.txt`. Highest compatibility score.
@@ -95,7 +95,7 @@ We evaluated the most prominent options for managing Python project dependencies
     *   **Performance:** Excellent. **Significantly faster** than all Python-based dependency managers and installers for resolution and installation. This is a major differentiating factor and aligns strongly with automating quickly.
     *   **Developer Experience (DX):** Excellent. Provides intuitive integrated CLI commands (`uv add`, `uv remove`, `uv update`, `uv run`, `uv build`, `uv publish`, `uv venv`). Comparable DX to PDM/Poetry for standard tasks.
     *   **Dependency Group Management:** Excellent. Supports standard `[project.optional-dependencies]` for defining groups and managing them via CLI.
-    *   **Integration:** High (Growing Rapidly). Explicitly designed to replace/interoperate with standards ([:term:`venv`](python:venv-tutorial), [:py:mod:`pip`](pip-documentation)), works well with standard build processes. Integrations are rapidly being built due to its popularity.
+    *   **Integration:** High (Growing Rapidly). Explicitly designed to replace/interoperate with standards ([:term:`venv`](python:venv-tutorial), [pip](pip-documentation)), works well with standard build processes. Integrations are rapidly being built due to its popularity.
     *   **Maturity & Stability:** Moderate (Rapidly Developing). V0.x, fast-moving development. While technically robust and backed by solid engineering, it's not as historically battle-tested across *all* complex edge cases as 1.0+ tools. Carries some risk of minor behavioral changes or discovering new edge cases in v0.x.
     *   **Community & Documentation:** High (Exploding). Very active development, rapidly growing user base, excellent and quickly improving documentation.
 *   **Conclusion:** Delivers outstanding performance and a strong modern DX, now with PEP 621 editing capabilities. Its primary practical trade-off compared to more mature tools is its v0.x status, which implies a faster pace of change and less historical battle-testing across edge cases. However, its technical merits strongly align with the template's philosophy prioritizing speed and thoughtful design.
@@ -110,15 +110,15 @@ We evaluated the most prominent options for managing Python project dependencies
     *   **Performance:** Excellent. Inherits `uv`'s speed for core dependency operations.
     *   **Developer Experience (DX):** Very High. Provides a very clean, unified CLI (`rye init`, `rye add`, `rye run`, `rye build`, `rye publish`). Opinionated but can simplify workflow buy-in.
     *   **Dependency Group Management:** Excellent. Supports standard `[project.optional-dependencies]`.
-    *   **Integration:** Moderate (Growing). As an all-in-one, tools need to interact with `rye run` or be compatible with its env structure. Less explicit support yet than for [:term:`PDM`](pdm-documentation)/[:term:`Poetry`](poetry-documentation)/[:py:mod:`pip`](pip-documentation)+[:term:`venv`](python:venv-tutorial).
+    *   **Integration:** Moderate (Growing). As an all-in-one, tools need to interact with `rye run` or be compatible with its env structure. Less explicit support yet than for [:term:`PDM`](pdm-documentation)/[:term:`Poetry`](poetry-documentation)/[pip](pip-documentation)+[:term:`venv`](python:venv-tutorial).
     *   **Maturity & Stability:** Low (Experimental). **Explicitly labeled experimental**. Subject to breaking changes and design evolution. This is the most significant factor for a foundation template.
     *   **Community & Documentation:** High (Active, niche). Very active development due to creator profile. Rapid adoption among early adopters.
 *   **Conclusion:** Highly promising unified workflow tool built on [:term:`uv`](uv-documentation)'s performance. However, its **experimental status** makes it too high-risk for a template aiming to provide a *robust* foundation based on current, albeit rapidly developing, *stable* tooling. A tool marked "experimental" should not be the default cornerstone of a widely used template unless the user explicitly opts into that level of risk.
 
 ## Chosen Tool(s)
 
 *   **[:term:`uv`](uv-documentation)** as the primary **Dependency Manager**.
-*   **[:py:class:`virtualenv`](virtualenv-documentation) / [:py:mod:`venv`](python:venv-tutorial)** (orchestrated by uv) for environment management.
+*   **[:py:class:`virtualenv`](virtualenv-documentation) / [venv](python:venv-tutorial)** (orchestrated by uv) for environment management.
 
 ## Justification for the Choice