Python Sphinx Autodoc — Core Concepts

What Sphinx Autodoc Does

Sphinx is Python’s de facto documentation generator. The autodoc extension is what makes it special: it imports your Python modules, reads docstrings, and renders them as structured documentation pages. You write docs inside your code, and Sphinx turns them into HTML, PDF, or ePub.

Setup in Three Steps

1. Install Sphinx:

   pip install sphinx
   sphinx-quickstart docs/

2. Enable autodoc in docs/conf.py:

   extensions = ["sphinx.ext.autodoc", "sphinx.ext.napoleon"]

3. Reference your code in .rst files:

   API Reference
   =============
   
   .. automodule:: mypackage.core
      :members:
      :undoc-members:
      :show-inheritance:

Run make html inside the docs/ folder, and Sphinx produces a complete website.

How Autodoc Finds Docstrings

When Sphinx encounters .. automodule::, it imports the specified module and inspects every class, function, and attribute. For each one with a docstring, it generates formatted documentation.

The key directives:

Directive	What It Documents
.. automodule::	Entire module
.. autoclass::	Single class with methods
.. autofunction::	Single function
.. autoattribute::	Class or module attribute

The :members: option includes all public members. :undoc-members: includes items without docstrings (showing their signature but no description). :show-inheritance: adds the class hierarchy.

Napoleon: Modern Docstring Styles

Raw reStructuredText docstrings are hard to read in source code. The Napoleon extension lets you use Google or NumPy style instead:

def transfer(source: str, destination: str, amount: float) -> bool:
    """Transfer funds between accounts.

    Args:
        source: Account ID to debit.
        destination: Account ID to credit.
        amount: Transfer amount in base currency.

    Returns:
        True if the transfer completed successfully.

    Raises:
        InsufficientFundsError: If the source balance is too low.
    """

Napoleon converts this into proper Sphinx markup at build time, so the HTML output is identical to hand-written reST but the source is far more readable.

Intersphinx: Cross-Project Links

The intersphinx extension lets your docs link directly to other projects’ documentation:

extensions = ["sphinx.ext.intersphinx"]

intersphinx_mapping = {
    "python": ("https://docs.python.org/3", None),
    "requests": ("https://requests.readthedocs.io/en/latest/", None),
}

Now a type hint like -> requests.Response automatically becomes a clickable link to the Requests documentation.

Common Misconception

“Sphinx only works with reStructuredText.” Since Sphinx 3.0+ and the MyST-Parser extension, you can write documentation pages in Markdown while still using autodoc for API reference. Many modern projects use Markdown for guides and let autodoc handle the API pages.

One thing to remember: Sphinx autodoc bridges the gap between code and docs — docstrings become the single source of truth, and the website updates every time you rebuild.