Sphinx: Project Setup, reST & Configuration

Sphinx was built for Python's own documentation and became the de facto standard for API reference docs across the Python ecosystem -- it converts plain-text source (reStructuredText, or Markdown via MyST) into HTML, PDF, and other formats, with purpose-built machinery for pulling docs directly from code.

Project Structure & conf.py

pip install sphinx
sphinx-quickstart docs   # scaffolds conf.py, index.rst, Makefile

# Build HTML output
cd docs && make html
# or directly:
sphinx-build -b html docs/ docs/_build/html

# docs/conf.py -- real Python, not just static config values
project = 'MyPackage'
version = '1.2.0'

extensions = [
    'sphinx.ext.autodoc',      # pull docstrings from source code
    'sphinx.ext.napoleon',      # parse Google/NumPy-style docstrings
    'sphinx.ext.intersphinx',   # cross-reference OTHER projects' docs
    'sphinx.ext.viewcode',
]

intersphinx_mapping = {
    'python': ('https://docs.python.org/3', None),
}

html_theme = 'furo'  # or sphinx_rtd_theme, alabaster (built-in default)

# Catch broken internal cross-references as build warnings --
# nitpicky = True (or `sphinx-build -n`) is a good CI strictness check

reStructuredText Basics

Installation
============

Install via pip::

.. code-block:: bash

   pip install mypackage

.. note::

   Requires Python 3.9 or later.

See :func:`mypackage.core.process` for the main entry point, or the
full :doc:`api-reference` for everything else.

.. toctree::
   :maxdepth: 2

   installation
   usage
   api-reference

Markdown via MyST-Parser

# conf.py
extensions = ['myst_parser']
source_suffix = {'.rst': 'restructuredtext', '.md': 'markdown'}

# Lowers the barrier for contributors who prefer Markdown's simpler
# day-to-day syntax, while still getting Sphinx's autodoc, cross-
# referencing, and theming -- without reST's more verbose directives
# throughout every page.