Revert "docs: remove old role prefix from some broken sphinx extlinks"

This reverts commit 6e82979.

Author: 56kyle

docs/topics/02_dependency-management.md

@@ -26,17 +26,17 @@ 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<>` + {venv}`venv-tutorial<>` / {virtualenv}`virtualenv<>` (+ {pip-tools}`pip-tools<>`)
+### Option 1: {pip}`pip<>` + :python{venv}`venv-tutorial<>` / {virtualenv}`virtualenv<>` (+ {pip-tools}`pip-tools<>`)
 
 - **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<>` understands PEP 621 for installing from `pyproject.toml`. {pip-tools}`pip-tools<>` 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. {pip-tools}`pip-tools<>` is pure Python and cross-platform.
-  - **Performance:** Moderate. {pip}`pip<>`'s dependency resolver can be slow for large/complex graphs. `pip-compile` adds time. {venv}`venv-tutorial<>`/{virtualenv}`virtualenv<>` creation/activation faster than some, slower than others (like uv).
+  - **Performance:** Moderate. {pip}`pip<>`'s dependency resolver can be slow for large/complex graphs. `pip-compile` adds time. :python{venv}`venv-tutorial<>`/{virtualenv}`virtualenv<>` 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 {venv}`venv-tutorial<>`s, `pip install`, and `requirements.txt`. Highest compatibility score.
+  - **Integration:** Excellent. As the standard, most ecosystem tools inherently understand :python{venv}`venv-tutorial<>`s, `pip install`, and `requirements.txt`. Highest compatibility score.
   - **Maturity & Stability:** Very High. Extremely mature, battle-tested for years. Stable APIs.
   - **Community & Documentation:** Very High. Widely adopted, vast documentation, large community.
 - **Conclusion:** A very stable, compatible baseline. Strong reproducibility _when augmented with pip-tools_. However, its multi-step workflow and moderate performance make it less ideal compared to modern integrated tools for a template prioritizing streamlined developer experience and automation speed.
@@ -65,7 +65,7 @@ We evaluated the most prominent options for managing Python project dependencies
   - **OS Interoperability:** Very High. Python-based tool, works across OSs. Excellent support for standard virtual environments.
   - **Performance:** High. Resolver is robust and performs well on complex graphs (generally better in practice than Poetry on specific problematic cases reported by users), though not consistently at `uv`'s speed.
   - **Developer Experience (DX):** Excellent. Intuitive unified CLI (`pdm add`, `pdm remove`, `pdm update`, `pdm install`, `pdm run`, `pdm build`, `pdm publish`). Excellent dependency group management.
-  - **Integration:** High. Growing support due to PEP adherence. Works well with tools via standard {venv}`venv-tutorial<>` and `pdm run`.
+  - **Integration:** High. Growing support due to PEP adherence. Works well with tools via standard :python{venv}`venv-tutorial<>` and `pdm run`.
   - **Maturity & Stability:** High. Mature, stable, active community. Less legacy than setuptools/pip, slightly younger adoption scale than {poetry}`Poetry<>` but rapidly growing.
   - **Community & Documentation:** High. Active development and community, good documentation.
 - **Conclusion:** A strong contender that excels at adhering to **PEP 621** while offering excellent DX and robust performance. A very solid, mature choice. However, its performance is not the absolute peak achievable, leading us to evaluate the faster alternatives.
@@ -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 ({venv}`venv-tutorial<>`, {pip}`pip<>`), 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 (:python{venv}`venv-tutorial<>`, {pip}`pip<>`), 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,7 +110,7 @@ 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 {pdm}`PDM<>`/{poetry}`Poetry<>`/{pip}`pip<>`+{venv}`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 {pdm}`PDM<>`/{poetry}`Poetry<>`/{pip}`pip<>`+:python{venv}`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 {uv}`uv<>`'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.
@@ -134,7 +134,7 @@ While {uv}`uv<>` is a newer tool still under rapid development, its technical st
 
 {pdm}`PDM<>` was a strong alternative, particularly for its maturity and strict PEP 621 adherence, but ultimately did not offer the same level of performance benefit as {uv}`uv<>`. {poetry}`Poetry<>` was discounted primarily for its non-adherence to **PEP 621** declaration syntax and reported performance bottlenecks on specific complex dependency sets. {hatch}`Hatch<>`'s environment-centric model and lack of a single root lock file made it less aligned with the standard dependency management workflow sought for the primary manager. {uv}`Rye<>`'s "experimental" status made it unsuitable for a template's default foundation.
 
-By choosing {uv}`uv<>`, the template makes a deliberate, opinionated choice to favor a tool that offers tangible performance improvements and a modern DX while still respecting crucial standards like **PEP 621** and the standard {venv}`venv-tutorial<>` model.
+By choosing {uv}`uv<>`, the template makes a deliberate, opinionated choice to favor a tool that offers tangible performance improvements and a modern DX while still respecting crucial standards like **PEP 621** and the standard :python{venv}`venv-tutorial<>` model.
 
 ## Interactions with Other Topics
 

docs/topics/05_type-checking.md

@@ -37,7 +37,7 @@ We evaluated the primary static type checkers for Python:
   - **Performance:** Moderate. Can be slow on larger codebases or initial runs. Caching helps, but still generally slower than {pyright}`Pyright<>`. Impacts fast feedback loops.
   - **OS Interoperability:** Excellent. Pure Python package, works reliably across OSs.
   - **Integration:** Excellent. Widely supported, integrates well into editors (though real-time performance is a factor), {pre-commit}`pre-commit<>` (official hook exists but can be slow), Task Automation, CI/CD.
-  - **Support for Stubs:** Excellent. Deep integration with {typeshed}`typeshed<>` and the stub ecosystem.
+  - **Support for Stubs:** Excellent. Deep integration with :python{typeshed}`typeshed<>` and the stub ecosystem.
   - **Error Messages:** High. Generally clear, but can be verbose or challenging in complex cases.
   - **Maturity & Stability:** Very High. Extremely mature, stable, long-standing.
   - **Community & Documentation:** Very High. Large, active community, extensive documentation and resources.
@@ -52,7 +52,7 @@ We evaluated the primary static type checkers for Python:
   - **Performance:** Excellent. **Significantly faster** than {mypy}`Mypy<>`. Designed for fast incremental checks and overall lower analysis time. Much more practical for real-time editor feedback, fast pre-commit runs, and quicker CI.
   - **OS Interoperability:** High. Works on major OSs. Relies on Node.js runtime internally (often bundled in distributions), making installation/setup slightly more complex than pure Python tools, but seamless for users of common distributions (like `npm` or bundled wheels/binaries).
   - **Integration:** Excellent. Strong CLI (`pyright`). Integrates exceptionally well with editors (real-time analysis via Language Server Protocol), well-suited for fast {pre-commit}`pre-commit<>` hooks (better performance than {mypy}`Mypy<>`), Task Automation, CI/CD.
-  - **Support for Stubs:** Excellent. Works effectively with {typeshed}`typeshed<>` and other stub sources.
+  - **Support for Stubs:** Excellent. Works effectively with :python{typeshed}`typeshed<>` and other stub sources.
   - **Error Messages:** Very High. Generally very clear, precise, and actionable messages.
   - **Maturity & Stability:** High. Mature, actively developed by Microsoft. Large user base, especially via :pyright-documentation - part of Pyright documentation:`Pylance`. Stable for production use.
   - **Community & Documentation:** High. Strong community (especially VS Code users), extensive documentation (though sometimes focused on :pyright-documentation - part of Pyright documentation:`Pylance`).
@@ -67,7 +67,7 @@ We evaluated the primary static type checkers for Python:
   - **Performance:** Moderate. Can be faster than {mypy}`Mypy<>` on initial runs for some codebases due to backend, but not typically as fast as {pyright}`Pyright<>` for incremental checks.
   - **OS Interoperability:** Excellent. Pure Python package, works reliably across OSs.
   - **Integration:** High. CLI tool for Task Automation and CI. Less common for real-time editor feedback or fast pre-commit due to performance and focus.
-  - **Support for Stubs:** Very High. Deep integration with {typeshed}`typeshed<>` and excels at type inference.
+  - **Support for Stubs:** Very High. Deep integration with :python{typeshed}`typeshed<>` and excels at type inference.
   - **Error Messages:** Moderate to High. Can be less precise in inference scenarios.
   - **Maturity & Stability:** High. Mature, actively developed at Google. Community outside Google is smaller than {mypy}`Mypy<>` or {pyright}`Pyright<>`.
 - **Conclusion:** Best suited for gradually adding typing to unannotated codebases. For a template that _mandates_ or strongly encourages type hints, its core strength (inference) is less relevant, and its performance and strictness on explicit hints are not better than {mypy}`Mypy<>` or {pyright}`Pyright<>`.

docs/topics/10_packaging-publish.md

@@ -8,7 +8,7 @@ This section evaluates tools and approaches for uploading Python distribution pa
 - Handle authentication with the package index securely.
 - Integrate seamlessly into automated workflows (Task Automation, CI/CD).
 - Ensure the publishing process is OS-interoperable.
-- Produce packages compatible with installation by standard tools like [{pip}`mod<>`](pip-documentation). (Addressed in Area 09's Build Process).
+- Produce packages compatible with installation by standard tools like [:py{pip}`mod<>`](pip-documentation). (Addressed in Area 09's Build Process).
 
 ## Evaluation Criteria
 

docs/topics/11_container-build.md

@@ -32,7 +32,7 @@ This section evaluates the process and tools for building application container
 
   - **Standardization (Format):** Excellent. `Dockerfile` is the **industry standard** text-based format for defining container images, widely understood and universally compatible across container runtimes.
   - **Best Practice Support:** Excellent. The `Dockerfile` syntax explicitly supports crucial best practices like **multistage builds** (`FROM ... AS <name>`), using the `USER` instruction for non-root users, selecting minimal base images (e.g., `python:3.x-slim`, Alpine, Distroless), managing dependency caching layers effectively via step ordering, copying standard artifacts (like built wheels from Area 09) instead of source. The tool (`docker build`/`podman build`) implements these features.
-  - **Packaging Integration:** Excellent. A standard `Dockerfile` workflow involves **copying the project's built wheel** (Area 09) into the image and installing it with [{pip}`mod<>`](pip-documentation) or the project's chosen manager ([`uv`](uv-documentation)). Alternatively, it can copy source/lock files and install dependencies with the manager directly _inside_ the build. This directly leverages the output of packaging and dependency management steps.
+  - **Packaging Integration:** Excellent. A standard `Dockerfile` workflow involves **copying the project's built wheel** (Area 09) into the image and installing it with [:py{pip}`mod<>`](pip-documentation) or the project's chosen manager ([`uv`](uv-documentation)). Alternatively, it can copy source/lock files and install dependencies with the manager directly _inside_ the build. This directly leverages the output of packaging and dependency management steps.
   - **Reproducibility:** High (Process). Given the same `Dockerfile`, build context files, and base image, the `docker build`/`podman build` process is highly reproducible layer-by-layer. Reliability of layer caching aids consistent builds.
   - **OS Interoperability (Tool):** Moderate (Runtime Dependency), Excellent (CLI). The `docker build` or `podman build` command-line tools are **OS-interoperable**. However, they require the {docker}`Docker<>` or {podman}`Podman<>` daemon/runtime to be installed and running on the host machine, which is an external dependency.
   - **CLI Usability:** Excellent. Simple command (`docker build . -t <image_name>`) is intuitive and standard.