Revert "docs: replace venv-tutorial with venv"

This reverts commit e0808ad.

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<>` / {virtualenv}`virtualenv<>` (+ {pip-tools}`pip-tools<>`)
+### Option 1: {pip}`pip<>` + {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<>`/{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. {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<>`s, `pip install`, and `requirements.txt`. Highest compatibility score.
+  - **Integration:** Excellent. As the standard, most ecosystem tools inherently understand {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<>` and `pdm run`.
+  - **Integration:** High. Growing support due to PEP adherence. Works well with tools via standard {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<>`, {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 ({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,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 {pdm}`PDM<>`/{poetry}`Poetry<>`/{pip}`pip<>`+{venv}`venv<>`.
+  - **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<>`.
   - **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.
 
 ## Chosen Tool(s)
 
 - **{uv}`uv<>`** as the primary **Dependency Manager**.
-- **{virtualenv}`virtualenv<>` / {venv}`venv<>`** (orchestrated by uv) for environment management.
+- **{virtualenv}`virtualenv<>` / {venv-tutorial}`venv<>`** (orchestrated by uv) for environment management.
 
 ## Justification for the Choice
 
@@ -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<>` 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 {venv}`venv-tutorial<>` model.
 
 ## Interactions with Other Topics