mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
115 lines
3.4 KiB
ReStructuredText
115 lines
3.4 KiB
ReStructuredText
=======
|
|
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 re-use 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
|
|
templating
|
|
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
|
|
|
|
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
|
|
glossary
|
|
changes
|
|
examples
|