===============
Examples
===============

Once Sphinx is :doc:`installed </usage/installation>`, you can proceed with
setting up your first Sphinx project. To ease the process of getting started,
Sphinx provides a tool, :program:`sphinx-quickstart`, which will generate a
documentation source directory and populate it with some defaults. We're going
to use the :program:`sphinx-quickstart` tool here, though it's use by no means
necessary.


Setting up the documentation sources
------------------------------------

The root directory of a Sphinx collection of :term:`reStructuredText` document
sources is called the :term:`source directory`.  This directory also contains
the Sphinx configuration file :file:`conf.py`, where you can configure all
aspects of how Sphinx reads your sources and builds your documentation.  [#]_

Sphinx comes with a script called :program:`sphinx-quickstart` that sets up a
source directory and creates a default :file:`conf.py` with the most useful
configuration values from a few questions it asks you. To use this, run:

.. code-block:: shell

   $ sphinx-quickstart

Answer each question asked. Be sure to say yes to the ``autodoc`` extension, as
we will use this later.

There is also an automatic "API documentation" generator called
:program:`sphinx-apidoc`; see :doc:`/man/sphinx-apidoc` for details.


Defining document structure
---------------------------

Let's assume you've run :program:`sphinx-quickstart`.  It created a source
directory with :file:`conf.py` and a master document, :file:`index.rst` (if you
accepted the defaults).  The main function of the :term:`master document` is to
serve as a welcome page, and to contain the root of the "table of contents
tree" (or *toctree*).  This is one of the main things that Sphinx adds to
reStructuredText, a way to connect multiple files to a single hierarchy of
documents.

.. sidebar:: reStructuredText directives

   ``toctree`` is a reStructuredText :dfn:`directive`, a very versatile piece
   of markup.  Directives can have arguments, options and content.

   *Arguments* are given directly after the double colon following the
   directive's name.  Each directive decides whether it can have arguments, and
   how many.

   *Options* are given after the arguments, in form of a "field list".  The
   ``maxdepth`` is such an option for the ``toctree`` directive.

   *Content* follows the options or arguments after a blank line.  Each
   directive decides whether to allow content, and what to do with it.

   A common gotcha with directives is that **the first line of the content must
   be indented to the same level as the options are**.

The ``toctree`` directive initially is empty, and looks like so:

.. code-block:: rest

   .. toctree::
      :maxdepth: 2

You add documents listing them in the *content* of the directive:

.. code-block:: rest

   .. toctree::
      :maxdepth: 2

      usage/installation
      usage/quickstart
      ...

This is exactly how the ``toctree`` for this documentation looks.  The
documents to include are given as :term:`document name`\ s, which in short
means that you leave off the file name extension and use forward slashes
(``/``) as directory separators.

|more| Read more about :ref:`the toctree directive <toctree-directive>`.

You can now create the files you listed in the ``toctree`` and add content, and
their section titles will be inserted (up to the ``maxdepth`` level) at the
place where the ``toctree`` directive is placed.  Also, Sphinx now knows about
the order and hierarchy of your documents.  (They may contain ``toctree``
directives themselves, which means you can create deeply nested hierarchies if
necessary.)


Adding content
--------------

In Sphinx source files, you can use most features of standard
:term:`reStructuredText`.  There are also several features added by Sphinx.
For example, you can add cross-file references in a portable way (which works
for all output types) using the :rst:role:`ref` role.

For an example, if you are viewing the HTML version you can look at the source
for this document -- use the "Show Source" link in the sidebar.

.. todo:: Update the below link when we add new guides on these.

|more| See :doc:`/usage/restructuredtext/index` for a more in-depth
introduction to reStructuredText, including markup added by Sphinx.