summaryrefslogtreecommitdiffstats
path: root/doc/index.rst
blob: 6dfdb6d94e30d23f88a3aecae7f1fcc231ae8b0d (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
=======
Welcome
=======

.. epigraph:: 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 :ref:`built-in extensions
  <builtin-extensions>`, and much more functionality via :ref:`third-party
  extensions <third-party-extensions>`.
* **Themes:** modify the look and feel of outputs via :doc:`creating themes
  <development/theming>`, and reuse many :ref:`third-party themes
  <third-party-themes>`.
* **Contributed extensions:** dozens of extensions :ref:`contributed by users
  <third-party-extensions>`; most of them installable from PyPI.

.. _reStructuredText: https://docutils.sourceforge.io/rst.html
.. _Docutils: https://docutils.sourceforge.io/
.. _Pygments: https://pygments.org/

Sphinx uses the reStructuredText_ markup language by default, and can read
:ref:`MyST markdown <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.

.. seealso::

   The `Sphinx documentation Table of Contents <contents.html>`_ has
   a full list of this site's pages.

.. _get-started:

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

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

.. toctree::
   :maxdepth: 2
   :caption: Get started

   usage/quickstart
   usage/installation
   tutorial/index

.. _user-guides:

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 :ref:`get-started`.

.. toctree::
   :maxdepth: 2
   :caption: User Guides

   usage/index
   development/index
   latex
   extdev/index

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 :doc:`Sphinx contributors' guide <internals/contributing>` if you would
like to contribute to the project.

.. toctree::
   :maxdepth: 2
   :caption: Community

   support
   internals/index
   faq
   authors

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 :ref:`get-started` or :ref:`user-guides`.

.. toctree::
   :maxdepth: 2
   :caption: Reference

   man/index
   usage/configuration
   usage/extensions/index
   usage/restructuredtext/index
   glossary
   changes
   examples