# Sphinx — Python Documentation Generator

> Generate professional documentation from reStructuredText and Markdown with cross-references, API autodoc, and multiple output formats.

## Install

Save in your project root:

# Sphinx — Python Documentation Generator

## Quick Use
```bash
pip install sphinx
sphinx-quickstart docs
cd docs
make html
# open _build/html/index.html
```

## Introduction
Sphinx is the standard documentation tool for the Python ecosystem and many other projects. It compiles reStructuredText or Markdown source files into HTML, PDF, ePub, and man pages with automatic cross-referencing, API documentation extraction, and a rich extension ecosystem.

## What Sphinx Does
- Parses reStructuredText and MyST Markdown into a document tree
- Generates HTML, LaTeX/PDF, ePub, man pages, and plain text output
- Extracts API documentation from Python docstrings via the autodoc extension
- Builds cross-references between documents, modules, classes, and functions
- Supports themes, extensions, and custom directives for tailored output

## Architecture Overview
Sphinx reads a configuration file (conf.py) and a master document that defines the table of contents tree. The parser converts source files into an internal doctree (based on docutils nodes). Builder classes then transform the doctree into the target output format. Extensions hook into events during parsing and building to add directives, roles, and transformations. The autodoc extension introspects live Python objects to generate reference pages.

## Self-Hosting & Configuration
- Install via pip: `pip install sphinx`
- Run `sphinx-quickstart` to scaffold a project with `conf.py` and `index.rst`
- Add `sphinx.ext.autodoc` and `sphinx.ext.napoleon` for API documentation
- Install a theme like `furo` or `sphinx-rtd-theme` for polished HTML output
- Use `sphinx-autobuild` for live-reload during writing

## Key Features
- First-class Python API documentation with autodoc and type-hint support
- Rich cross-referencing across documents, code objects, and external projects via intersphinx
- 1000+ community extensions for diagrams, notebooks, OpenAPI specs, and more
- Multiple output formats from a single source (HTML, PDF, ePub, man)
- Internationalization support with gettext-based translation workflows

## Comparison with Similar Tools
- **MkDocs** — Markdown-native, simpler setup, but weaker cross-referencing and no autodoc
- **Docusaurus** — React-based, ideal for JavaScript projects; not Python-centric
- **pdoc** — minimal Python API docs generator; lacks narrative documentation support
- **Doxygen** — targets C/C++/Java; different markup language and ecosystem
- **mdBook** — Rust-oriented Markdown book builder; minimal plugin system

## FAQ
**Q: Can Sphinx use Markdown instead of reStructuredText?**
A: Yes. Install the MyST-Parser extension to write documentation in Markdown with full Sphinx directive support.

**Q: How do I generate PDF output?**
A: Run `make latexpdf`. Sphinx produces LaTeX source and compiles it with pdflatex or xelatex.

**Q: Does Sphinx work for non-Python projects?**
A: Yes. The Linux kernel, Blender, and many C/C++ projects use Sphinx. Language-specific domains are available for C, C++, JavaScript, and more.

**Q: How do I host the output?**
A: Build the HTML and deploy to any static host. Read the Docs provides free hosting with automatic builds on git push.

## Sources
- https://github.com/sphinx-doc/sphinx
- https://www.sphinx-doc.org/en/master/

---
Source: https://tokrepo.com/en/workflows/be3b593d-4211-11f1-9bc6-00163e2b0d79
Author: AI Open Source