Skip to content

Commit 109ccb4

Browse files
committed
docs: replace sphinx napoleon links with temp placeholder
1 parent 33a8cdb commit 109ccb4

File tree

1 file changed

+3
-3
lines changed

1 file changed

+3
-3
lines changed

docs/topics/07_documentation.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ We evaluated the leading tools for generating documentation in the Python ecosys
3333
- **Description:** The de-facto standard documentation generator for Python projects. Highly powerful and extensible. Primarily uses reStructuredText (reST) as its source format but supports Markdown via extensions like [:term:`MyST-Parser`](myst-parser-documentation). Excels at integrating with code via `autodoc`.
3434
- **Evaluation:**
3535

36-
- **API Generation (Docstrings & Hints):** Excellent. The `sphinx.ext.autodoc` extension is robust, mature, and widely used for extracting documentation from code based on docstrings (supporting **PEP 257**) and type hints. It integrates seamlessly with extensions like [:term:`sphinx-autodoc-typehints`](sphinxautodoctypehints-documentation) and [:term:`sphinx.ext.napoleon`](python:sphinx.ext.napoleon) (for Google/NumPy style).
36+
- **API Generation (Docstrings & Hints):** Excellent. The `sphinx.ext.autodoc` extension is robust, mature, and widely used for extracting documentation from code based on docstrings (supporting **PEP 257**) and type hints. It integrates seamlessly with extensions like [:term:`sphinx-autodoc-typehints`](sphinxautodoctypehints-documentation) and [:term:`sphinx.ext.napoleon`](sphinx-ext-napoleon-documentation) (for Google/NumPy style).
3737
- **Narrative Authoring:** Moderate (reST). Native reStructuredText is powerful but has a steeper learning curve than Markdown for many developers. Excellent (Markdown via MyST). Using the [:term:`MyST-Parser`](myst-parser-documentation) allows writing narrative content in more familiar Markdown while retaining Sphinx's advanced features.
3838
- **Content Combination:** Excellent. [:term:`Sphinx`](sphinx-documentation) is designed from the ground up to combine narrative content and API references with powerful cross-referencing, indexing, and navigation features.
3939
- **Build Process:** High. Building is done via the standard `sphinx-build` command, which is highly scriptable (`sphinx-build -b html docs docs/_build/html`). Configuration is in a Python file (`conf.py`), offering flexibility but requiring Python knowledge. Initial setup can involve some steps (running quickstart, configuring extensions).
@@ -67,14 +67,14 @@ We evaluated the leading tools for generating documentation in the Python ecosys
6767
- Primary Documentation Generator: **[:term:`Sphinx`](sphinx-documentation)**.
6868
- Source Format: **MyST Markdown** (via [:term:`MyST-Parser`](myst-parser-documentation)).
6969
- API Integration: **`sphinx.ext.autodoc`**.
70-
- Docstring/Hint Parsing: **[:term:`sphinx.ext.napoleon`](python:sphinx.ext.napoleon)** (Google style), **[:term:`sphinx-autodoc-typehints`](sphinxautodoctypehints-documentation)**.
70+
- Docstring/Hint Parsing: **[:term:`sphinx.ext.napoleon`](sphinx-ext-napoleon-documentation)** (Google style), **[:term:`sphinx-autodoc-typehints`](sphinxautodoctypehints-documentation)**.
7171
- Docstring Linter Helper: **[:term:`pydocstyle`](pydocstyle-documentation)** (Checks rules used by generator).
7272

7373
## Justification for the Choice
7474

7575
**[:term:`Sphinx`](sphinx-documentation)** combined with **MyST Markdown** and essential extensions is the best choice for documentation based on its power, standards adherence, and flexibility, while addressing the ease-of-use barrier of its native format:
7676

77-
1. **Robust API Documentation:** [:term:`Sphinx`](sphinx-documentation) with `autodoc` is the **standard and most robust method** for extracting documentation directly from Python code's docstrings (following **PEP 257**) and type hints. Integrated with [:term:`sphinx.ext.napoleon`](python:sphinx.ext.napoleon) (for Google style) and [:term:`sphinx-autodoc-typehints`](sphinxautodoctypehints-documentation) (for type hints), it ensures high-quality, automatically updated API references. This directly serves the **"Documented is better than implied"** philosophy and **API Generation** goal. We use **[:term:`pydocstyle`](pydocstyle-documentation)** (checked via [:term:`Ruff`](ruff-documentation) in Topic 04/12) to help ensure docstrings meet the necessary standards for [:term:`Sphinx`](sphinx-documentation).
77+
1. **Robust API Documentation:** [:term:`Sphinx`](sphinx-documentation) with `autodoc` is the **standard and most robust method** for extracting documentation directly from Python code's docstrings (following **PEP 257**) and type hints. Integrated with [:term:`sphinx.ext.napoleon`](sphinx-ext-napoleon-documentation) (for Google style) and [:term:`sphinx-autodoc-typehints`](sphinxautodoctypehints-documentation) (for type hints), it ensures high-quality, automatically updated API references. This directly serves the **"Documented is better than implied"** philosophy and **API Generation** goal. We use **[:term:`pydocstyle`](pydocstyle-documentation)** (checked via [:term:`Ruff`](ruff-documentation) in Topic 04/12) to help ensure docstrings meet the necessary standards for [:term:`Sphinx`](sphinx-documentation).
7878
2. **Flexibility & Power:** [:term:`Sphinx`](sphinx-documentation) offers unparalleled flexibility for structuring documentation (including complex hierarchies, indices, bibliographies if needed), powerful cross-referencing (linking between API docs, narrative sections, and even external project docs via [:term:`intersphinx`](sphinx-documentation)), and a vast extension ecosystem (addressing **Content Combination**, **Output Quality**, **Extensibility**).
7979
3. **Markdown Authoring:** By using the **[:term:`MyST-Parser`](myst-parser-documentation)** extension, narrative documentation can be written using familiar **Markdown** syntax, significantly lowering the barrier to contribution for most developers compared to reStructuredText (addressing **Narrative Authoring** while keeping Sphinx's power).
8080
4. **Reliable & OS-Interoperable Build:** The [:term:`Sphinx`](sphinx-documentation) build process is mature, **scriptable**, and **highly OS-interoperable**, running reliably across Linux, macOS, and Windows (addressing **Build Process** and **OS Interoperability**).

0 commit comments

Comments
 (0)