Welcome
*******

   Sphinx makes it easy to create intelligent and beautiful
   documentation.

Here are some of Sphinx's major features:

* **Output formats:** HTML (including Windows HTML Help), LaTeX (for
  printable PDF versions), ePub, Texinfo, manual pages, plain text

* **Extensive cross-references:** semantic markup and automatic links
  for functions, classes, citations, glossary terms and similar pieces
  of information

* **Hierarchical structure:** easy definition of a document tree, with
  automatic links to siblings, parents and children

* **Automatic indices:** general index as well as a language-specific
  module indices

* **Code handling:** automatic highlighting using the Pygments
  highlighter

* **Extensions:** automatic testing of code snippets, inclusion of
  docstrings from Python modules (API docs) via built-in extensions,
  and much more functionality via third-party extensions.

* **Themes:** modify the look and feel of outputs via creating themes,
  and re-use many third-party themes.

* **Contributed extensions:** dozens of extensions contributed by
  users; most of them installable from PyPI.

Sphinx uses the reStructuredText markup language by default, and can
read MyST markdown via third-party extensions. Both of these are
powerful and straightforward to use, and have functionality for
complex documentation and publishing workflows. They both build upon
Docutils to parse and write documents.

See below for how to navigate Sphinx's documentation.

See also:

  The Sphinx documentation Table of Contents has a full list of this
  site's pages.


Get started
===========

These sections cover the basics of getting started with Sphinx,
including creating and building your own documentation from scratch.


Get started
^^^^^^^^^^^

* Getting Started

  * Setting up the documentation sources

  * Defining document structure

  * Adding content

  * Running the build

  * Documenting objects

  * Basic configuration

  * Autodoc

  * Intersphinx

  * More topics to be covered

* Installing Sphinx

  * Overview

  * Linux

  * macOS

  * Windows

  * Installation from PyPI

  * Docker

  * Installation from source

* Tutorial: Build your first project

  * Getting started

  * First steps to document your project using Sphinx

  * More Sphinx customization

  * Narrative documentation in Sphinx

  * Describing code in Sphinx

  * Automatic documentation generation from code

  * Appendix: Deploying a Sphinx project online

  * Where to go from here


User Guides
===========

These sections cover various topics in using and extending Sphinx for
various use-cases. They are a comprehensive guide to using Sphinx in
many contexts and assume more knowledge of Sphinx. If you are new to
Sphinx, we recommend starting with Get started.


User Guides
^^^^^^^^^^^

* Using Sphinx

  * reStructuredText

  * Markdown

  * Configuration

  * Builders

  * Extensions

  * HTML Theming

  * Internationalization

  * Sphinx Web Support

* Writing Sphinx Extensions

  * Developing extensions overview

  * Extension tutorials

  * Configuring builders

  * Templating

  * HTML theme development

* LaTeX customization

  * The "latex_elements" configuration setting

  * The "sphinxsetup" configuration setting

  * Additional  CSS-like "'sphinxsetup'" keys

  * LaTeX macros and environments

* Sphinx Extensions API

  * Important objects

  * Build Phases

  * Extension metadata

  * APIs used for writing extensions


Community guide
===============

Sphinx is community supported and welcomes contributions from anybody.
The sections below should help you get started joining the Sphinx
community as well as contributing.

See the Sphinx contributors' guide if you would like to contribute to
the project.


Community
^^^^^^^^^

* Get support

* Contribute to Sphinx

  * Contributing to Sphinx

  * Sphinx's release process

  * Organization of the Sphinx project

  * Sphinx Code of Conduct

* Sphinx FAQ

  * How do I...

  * Using Sphinx with...

  * Sphinx vs. Docutils

  * Epub info

  * Texinfo info

* Sphinx authors

  * Maintainers

  * Contributors


Reference guide
===============

Reference documentation is more complete and programmatic in nature,
it is a collection of information that can be quickly referenced. If
you would like usecase-driven documentation, see Get started or User
Guides.


Reference
^^^^^^^^^

* Command-Line Tools

  * Core Applications

  * Additional Applications

* Configuration

  * Project information

  * General configuration

  * Options for internationalization

  * Options for Math

  * Options for HTML output

  * Options for Single HTML output

  * Options for HTML help output

  * Options for Apple Help output

  * Options for epub output

  * Options for LaTeX output

  * Options for text output

  * Options for manual page output

  * Options for Texinfo output

  * Options for QtHelp output

  * Options for the linkcheck builder

  * Options for the XML builder

  * Options for the C domain

  * Options for the C++ domain

  * Options for the Python domain

  * Options for the Javascript domain

  * Example of configuration file

* Extensions

  * Built-in extensions

  * Third-party extensions

* reStructuredText

  * reStructuredText Primer

  * Roles

  * Directives

  * Field Lists

  * Domains

* Glossary

* Changelog

* Projects using Sphinx

  * Documentation using the alabaster theme

  * Documentation using the classic theme

  * Documentation using the sphinxdoc theme

  * Documentation using the nature theme

  * Documentation using another builtin theme

  * Documentation using sphinx_rtd_theme

  * Documentation using sphinx_bootstrap_theme

  * Documentation using pydata_sphinx_theme

  * Documentation using a custom theme or integrated in a website

  * Homepages and other non-documentation sites

  * Books produced using Sphinx

  * Theses produced using Sphinx

  * Projects integrating Sphinx functionality
