docs: convert all custom text links that plan on using ext links to have pretend terms to allow for easier replacements

Author: 56kyle

docs/getting-started-template-contributing.md

@@ -8,7 +8,7 @@ To contribute to the template, you will need:
 
 1.  **Git**: For version control.
 2.  **Python 3.9+**: We recommend using a supported Python version.
-3.  **uv**: Our chosen dependency manager (see [Dependency Management (02)](topics/02_dependency-management.md)). Install `uv` globally or in a base environment following the official [uv installation guide](uv-install-documentation).
+3.  **uv**: Our chosen dependency manager (see [Dependency Management (02)](topics/02_dependency-management.md)). Install `uv` globally or in a base environment following the official [:term:`uv installation guide`](uv-install-documentation).
 4.  **Docker or Podman**: Required for testing the containerization aspects of the generated template (see [Container Build (11)](topics/11_container-build.md), [Dev Containers (17)](topics/17_dev-containers.md)).
 5.  **Task Automation Tools**: The template itself uses a `noxfile.py` to manage its own development and documentation build workflows. Install `nox`:
     ```bash

docs/quickstart.md

@@ -12,8 +12,8 @@ Make sure you have these installed:
 
 - **Python 3.9+** (or your chosen template version).
 - **Git**.
-- **uv**: Our chosen dependency manager. Install it [officially](uv-install-documentation).
-- **Docker or Podman**: If you plan to work with containers (most web apps will need this). Install [Docker](docker-install-documentation) or [Podman](podman-install-documentation).
+- **uv**: Our chosen dependency manager. Install it [:term:`officially`](uv-install-documentation).
+- **Docker or Podman**: If you plan to work with containers (most web apps will need this). Install [:term:`Docker`](docker-install-documentation) or [:term:`Podman`](podman-install-documentation).
 
 ## 2. Create Your Project
 

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: [pip](pip-documentation) + [:term:`venv`](venv-documentation) / [:term:`virtualenv`](virtualenv-documentation) (+ [:term:`pip-tools`](pip-tools-documentation))
+### Option 1: [:term:`pip`](pip-documentation) + [:term:`venv`](venv-documentation) / [: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. [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. [:term:`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. [pip](pip-documentation)'s dependency resolver can be slow for large/complex graphs. `pip-compile` adds time. [:term:`venv`](venv-documentation)/[:term:`virtualenv`](virtualenv-documentation) creation/activation faster than some, slower than others (like uv).
+  - **Performance:** Moderate. [:term:`pip`](pip-documentation)'s dependency resolver can be slow for large/complex graphs. `pip-compile` adds time. [:term:`venv`](venv-documentation)/[: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`](venv-documentation)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`](venv-documentation), [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`](venv-documentation), [:term:`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)/[pip](pip-documentation)+[:term:`venv`](venv-documentation).
+  - **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)/[:term:`pip`](pip-documentation)+[:term:`venv`](venv-documentation).
   - **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) / [venv](venv-documentation)** (orchestrated by uv) for environment management.
+- **[:term:`virtualenv`](virtualenv-documentation) / [:term:`venv`](venv-documentation)** (orchestrated by uv) for environment management.
 
 ## Justification for the Choice
 
@@ -139,7 +139,7 @@ By choosing [:term:`uv`](uv-documentation), the template makes a deliberate, opi
 ## Interactions with Other Topics
 
 - **pyproject.toml (01):** [:term:`uv`](uv-documentation) is the primary consumer and editor of the `[project]`, `[build-system]`, and `[project.optional-dependencies]` tables in `pyproject.toml`, acting as the interpreter for packaging standards. Its own configuration goes in `[tool.uv]`.
-- **Packaging Build (09):** [:term:`uv`](uv-documentation) acts as a PEP 517 build frontend (`uv build`), calling the appropriate backend ([`setuptools`](setuptools-documentation) or [`maturin`](maturin-documentation)) configured in `pyproject.toml`.
+- **Packaging Build (09):** [:term:`uv`](uv-documentation) acts as a PEP 517 build frontend (`uv build`), calling the appropriate backend ([:term:`setuptools`](setuptools-documentation) or [:term:`maturin`](maturin-documentation)) configured in `pyproject.toml`.
 - **Packaging Publish (10):** [:term:`uv`](uv-documentation) provides a command to publish packages (`uv publish`) as an alternative to using [:term:`twine`](twine-documentation) directly. The Task Automation layer (12) might call `uv publish`.
 - **Task Automation (12):** [:term:`Nox`](nox-documentation) will orchestrate workflows by calling [:term:`uv`](uv-documentation) commands (e.g., `uv run ruff check`, `uv run pytest`, `uv build`, `uv publish`). [:term:`uv`](uv-documentation) is also configured as the backend for Nox's virtual environments (`nox.options.default_venv_backend = "uv"`), ensuring all session environments are created and managed with [:term:`uv`](uv-documentation)'s performance.
 - **Container Build (11):** [:term:`uv`](uv-documentation) is the recommended tool for installing dependencies _inside_ the `Dockerfile` (`RUN uv sync`).

docs/topics/03_code-formatting.md

@@ -33,7 +33,7 @@ We evaluated the leading options for automated code formatting:
   - **Opinionatedness & Configuration:** Very High. Famously requires minimal configuration (`--line-length` is a common option). Aligns with the "Opinionated is better than impartial" philosophy.
   - **Performance:** Good. Reasonably fast for typical file sizes and project sizes. Noticeably slower than Rust-based alternatives like [:term:`Ruff`](ruff-documentation) on larger codebases or when run very frequently.
   - **OS Interoperability:** Excellent. Pure Python package, works reliably on all major operating systems.
-  - **Integration:** Excellent. Long-standing standard, strong integration with [:term:`pre-commit`](pre-commit-documentation), [:term:`Nox`](nox-documentation)/[:term:`uv` run](uv-documentation), CI platforms, and almost all editors/IDEs.
+  - **Integration:** Excellent. Long-standing standard, strong integration with [:term:`pre-commit`](pre-commit-documentation), [:term:`Nox`](nox-documentation)/[:term:`uv run`](uv-documentation), CI platforms, and almost all editors/IDEs.
   - **Tool Count:** Moderate. Requires using two separate tools (`black`, `isort`) for the complete formatting task (code style + import sorting). Adds a small layer of management (dependencies, running both).
   - **Maturity & Stability:** Very High. Mature, stable, widely used standard.
   - **Community & Documentation:** Very High. Large, active community, extensive documentation.
@@ -79,7 +79,7 @@ We evaluated the leading options for automated code formatting:
   - **Opinionatedness & Configuration:** Very High. Highly opinionated with minimal configuration, inheriting philosophy from [:term:`Black`](black-documentation). Configuration is shared with the linter in `pyproject.toml` or `.ruff.toml`.
   - **Performance:** Excellent. **Orders of magnitude faster** than all Python-based formatters ([:term:`Black`](black-documentation), [:term:`isort`](isort-documentation), [:term:`autopep8`](autopep8-documentation), [:term:`yapf`](yapf-documentation)). This is a major practical advantage, especially for pre-commit hooks and large projects.
   - **OS Interoperability:** Excellent. Rust binary, works natively and reliably across all major operating systems.
-  - **Integration:** Excellent and Growing Rapidly. Native support in [:term:`pre-commit`](pre-commit-documentation), easily callable via CLI for [:term:`Nox`](nox-documentation)/[:term:`uv` run](uv-documentation), integrates into CI, rapidly gaining editor/IDE support due to its speed and dual formatting/linting capabilities.
+  - **Integration:** Excellent and Growing Rapidly. Native support in [:term:`pre-commit`](pre-commit-documentation), easily callable via CLI for [:term:`Nox`](nox-documentation)/[:term:`uv run`](uv-documentation), integrates into CI, rapidly gaining editor/IDE support due to its speed and dual formatting/linting capabilities.
   - **Tool Count:** Excellent. **Consolidates code formatting AND import sorting** into a single tool and command (`ruff format`).
   - **Maturity & Stability:** High (Formatter is newer than Linter, but built on stable core). [:term:`Ruff`](ruff-documentation) as a project is very mature. The formatter feature itself is newer but built on the same highly performant core and rapidly stabilizing, considered production-ready by its authors.
   - **Community & Documentation:** High (Exploding). Very active development, massive and rapidly growing user base, excellent and extensive documentation.

docs/topics/04_code-linting.md

@@ -38,7 +38,7 @@ We evaluated the leading options for Python code linting and static analysis:
   - **Configurable:** High. Configurable via `.flake8`, `setup.cfg`, or `pyproject.toml` (`[flake8]`). Default checks are standard, but many plugins require explicit configuration.
   - **Performance:** Moderate. As a Python tool wrapping other Python tools, performance is acceptable for many projects but noticeably slower than Rust-based alternatives, potentially impacting editor feedback speed or pre-commit hook viability on large codebases.
   - **OS Interoperability:** Excellent. Pure Python package, works reliably across Linux, macOS, and Windows.
-  - **Integration:** Excellent. A long-standing standard, deep integration across editors/IDEs, [:term:`pre-commit`](pre-commit-documentation) (official hook), [:term:`Nox`](nox-documentation)/[:term:`uv` run](uv-documentation), CI/CD platforms.
+  - **Integration:** Excellent. A long-standing standard, deep integration across editors/IDEs, [:term:`pre-commit`](pre-commit-documentation) (official hook), [:term:`Nox`](nox-documentation)/[:term:`uv run`](uv-documentation), CI/CD platforms.
   - **Tool Count:** Moderate. It's a wrapper, so requires installing [:term:`flake8`](flake8-documentation) itself plus desired plugins. Simpler than installing PyFlakes, pycodestyle, etc. separately. Often used alongside a formatter.
   - **Maturity & Stability:** Very High. Mature, stable, widely adopted for many years.
   - **Community & Documentation:** Very High. Large, active community, extensive documentation for both base [:term:`flake8`](flake8-documentation) and its plugins.
@@ -91,7 +91,7 @@ We evaluated the leading options for Python code linting and static analysis:
   - **Configurable:** High. Configurable via `.ruff.toml` or `pyproject.toml`. Powerful and flexible rule selection. Default set includes core checks, adding more rules (like Pylint conventions) is explicit.
   - **Performance:** Excellent. **Orders of magnitude faster** than Python-based linters. Transformative for developer workflow feedback loops (real-time checks in editors, pre-commit speed) and CI times.
   - **OS Interoperability:** Excellent. Rust binary, works natively and reliably across all major operating systems.
-  - **Integration:** Excellent. Rapidly gaining ecosystem integration. Native [:term:`pre-commit`](pre-commit-documentation) hook (highly recommended due to speed). Easily callable via CLI for [:term:`Nox`](nox-documentation)/[:term:`uv` run](uv-documentation), integrates into CI, strong and increasing editor/IDE support.
+  - **Integration:** Excellent. Rapidly gaining ecosystem integration. Native [:term:`pre-commit`](pre-commit-documentation) hook (highly recommended due to speed). Easily callable via CLI for [:term:`Nox`](nox-documentation)/[:term:`uv run`](uv-documentation), integrates into CI, strong and increasing editor/IDE support.
   - **Tool Count:** Excellent. **Consolidates the functionality of multiple separate linters** into a single binary and configuration file. Also includes formatting.
   - **Maturity & Stability:** Very High (Linter). [:term:`Ruff`](ruff-documentation) as a linter is mature, stable, and very widely adopted. The project has a massive and active community.
   - **Community & Documentation:** Very High (Exploding). Very active development, massive and rapidly growing user base, excellent and extensive documentation.