You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/topics/07_documentation.md
+3-3Lines changed: 3 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -33,7 +33,7 @@ We evaluated the leading tools for generating documentation in the Python ecosys
33
33
-**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`.
34
34
-**Evaluation:**
35
35
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).
37
37
-**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.
38
38
-**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.
39
39
-**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
- Docstring Linter Helper: **[:term:`pydocstyle`](pydocstyle-documentation)** (Checks rules used by generator).
72
72
73
73
## Justification for the Choice
74
74
75
75
**[: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:
76
76
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).
78
78
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**).
79
79
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).
80
80
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