doc/developer-guide/documentation/rst-and-sphinx.en.rst

.. Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
   distributed with this work for additional information
   regarding copyright ownership.  The ASF licenses this file
   to you under the Apache License, Version 2.0 (the
   "License"); you may not use this file except in compliance
   with the License.  You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing,
   software distributed under the License is distributed on an
   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
   KIND, either express or implied.  See the License for the
   specific language governing permissions and limitations
   under the License.

.. include:: ../../common.defs

.. _developer-doc-rst-and-sphinx:

|RST| and Sphinx
****************

The |TS| documentation source files are written using |RST| (RST) markup. This
is a plain-text format intended to be easily readable both in its source and
final rendered forms. While not entirely dissimilar to other plain text markup
formats like Markdown, RST provides additional functionality for defining
internal links between documents, producing tables of contents, and indices.
Additionally, RST works in hand with Sphinx for providing advanced features
such as markup domains, of which this documentation makes extensive use.

Both |RST| and Sphinx have official documentation resources which detail their
full capabilities and all markup options, as well as methods of extending them
with custom markup. This section will explain the most common markup features
used, but the following resources may be consulted for further details.

- `reStructuredText Markup Specification <http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html>`_

- `Sphinx Documentation Generator <http://sphinx-doc.org/>`_

- `RST Primer by Sphinx <http://sphinx-doc.org/rest.html>`_