Sphinx: Autodoc, Cross-References & Publishing

Autodoc: Docs Derived from Code

# mypackage/core.py
def process(data: list[int], threshold: int = 0) -> list[int]:
    """Filter and process a list of integers.

    Args:
        data: The input integers to process.
        threshold: Minimum value to include (default 0).

    Returns:
        The filtered, processed list.

    Raises:
        ValueError: If data is empty.
    """
    if not data:
        raise ValueError("data must not be empty")
    return [x for x in data if x >= threshold]

.. api-reference.rst -- pulls the docstring above directly, kept in
   sync automatically since it reads the live source at build time

API Reference
=============

.. automodule:: mypackage.core
   :members:
   :undoc-members:

.. or scaffold these stub files automatically for a whole package:
.. $ sphinx-apidoc -o docs/api mypackage/

Cross-References & Domains

• :func:`mymodule.myfunc`, :class:`MyClass`, :ref:`some-label` -- create real, build-validated hyperlinks, not plain unlinked text or hand-maintained URLs.

• The Python domain (:py:func:, :py:class:) gives cross-references semantic meaning -- domains also exist for C, C++, JavaScript, and more.

• intersphinx links to ANOTHER project's docs (e.g. Python's own stdlib reference) by reading its object inventory -- no hardcoded external URLs to go stale.

• nitpicky mode warns on every unresolvable cross-reference -- catches broken internal links as a CI-failable check.

Publishing: Read the Docs

• Connects to a git repo -- automatically rebuilds and republishes docs on every push (often per-branch/per-tag too).

• Because autodoc pulls live from current docstrings, each rebuild reflects the actual current codebase -- reduces (doesn't eliminate) reference docs silently drifting out of sync with code.

• Very common pairing specifically for open-source Python projects.

Sphinx vs Lighter-Weight Tools

• Sphinx's autodoc/domains/cross-referencing earns its complexity for code-heavy API reference documentation.

• A mostly-prose guides/tutorial site with less deep code-derived reference material may find MkDocs's simpler Markdown-first setup a better fit for that specific content shape.