Commits

Georg Brandl  committed ca1aea7

Begin the Great Refactoring of the docs.

* Move sphinx-build option description from intro to a new document.
* Move toctree information to a new document in markup/.
* Add a tutorial document placed after intro. Begin filling it in.

  • Participants
  • Parent commits bb44240

Comments (0)

Files changed (11)

File doc/concepts.rst

-.. highlight:: rest
-
-.. _concepts:
-
-Sphinx concepts
-===============
-
-Document names
---------------
-
-Since the reST source files can have different extensions (some people like
-``.txt``, some like ``.rst`` -- the extension can be configured with
-:confval:`source_suffix`) and different OSes have different path separators,
-Sphinx abstracts them: all "document names" are relative to the :term:`source
-directory`, the extension is stripped, and path separators are converted to
-slashes.  All values, parameters and suchlike referring to "documents" expect
-such a document name.
-
-Examples for document names are ``index``, ``library/zipfile``, or
-``reference/datamodel/types``.  Note that there is no leading slash.
-
-
-The TOC tree
-------------
-
-.. index:: pair: table of; contents
-
-Since reST does not have facilities to interconnect several documents, or split
-documents into multiple output files, Sphinx uses a custom directive to add
-relations between the single files the documentation is made of, as well as
-tables of contents.  The ``toctree`` directive is the central element.
-
-.. directive:: toctree
-
-   This directive inserts a "TOC tree" at the current location, using the
-   individual TOCs (including "sub-TOC trees") of the documents given in the
-   directive body (whose path is relative to the document the directive occurs
-   in).  A numeric ``maxdepth`` option may be given to indicate the depth of the
-   tree; by default, all levels are included. [#]_
-
-   Consider this example (taken from the Python docs' library reference index)::
-
-      .. toctree::
-         :maxdepth: 2
-
-         intro
-         strings
-         datatypes
-         numeric
-         (many more documents listed here)
-
-   This accomplishes two things:
-
-   * Tables of contents from all those documents are inserted, with a maximum
-     depth of two, that means one nested heading.  ``toctree`` directives in
-     those documents are also taken into account.
-   * Sphinx knows that the relative order of the documents ``intro``,
-     ``strings`` and so forth, and it knows that they are children of the shown
-     document, the library index.  From this information it generates "next
-     chapter", "previous chapter" and "parent chapter" links.
-
-   Document titles in the :dir:`toctree` will be automatically read from the
-   title of the referenced document. If that isn't what you want, you can
-   specify an explicit title and target using a similar syntax to reST
-   hyperlinks (and Sphinx's :ref:`cross-referencing syntax <xref-syntax>`). This
-   looks like::
-
-       .. toctree::
-
-          intro
-          All about strings <strings>
-          datatypes
-
-   The second line above will link to the ``strings`` document, but will use the
-   title "All about strings" instead of the title of the ``strings`` document.
-
-   You can also add external links, by giving an HTTP URL instead of a document
-   name.
-
-   If you want to have section numbers even in HTML output, give the toctree a
-   ``numbered`` flag option.  For example::
-
-      .. toctree::
-         :numbered:
-
-         foo
-         bar
-
-   Numbering then starts at the heading of ``foo``.  Sub-toctrees are
-   automatically numbered (don't give the ``numbered`` flag to those).
-
-   If you want only the titles of documents in the tree to show up, not other
-   headings of the same level, you can use the ``titlesonly`` option::
-
-      .. toctree::
-         :titlesonly:
-
-         foo
-         bar
-
-   You can use "globbing" in toctree directives, by giving the ``glob`` flag
-   option.  All entries are then matched against the list of available
-   documents, and matches are inserted into the list alphabetically.  Example::
-
-      .. toctree::
-         :glob:
-
-         intro*
-         recipe/*
-         *
-
-   This includes first all documents whose names start with ``intro``, then all
-   documents in the ``recipe`` folder, then all remaining documents (except the
-   one containing the directive, of course.) [#]_
-
-   The special entry name ``self`` stands for the document containing the
-   toctree directive.  This is useful if you want to generate a "sitemap" from
-   the toctree.
-
-   You can also give a "hidden" option to the directive, like this::
-
-      .. toctree::
-         :hidden:
-
-         doc_1
-         doc_2
-
-   This will still notify Sphinx of the document hierarchy, but not insert links
-   into the document at the location of the directive -- this makes sense if you
-   intend to insert these links yourself, in a different style, or in the HTML
-   sidebar.
-
-   In the end, all documents in the :term:`source directory` (or subdirectories)
-   must occur in some ``toctree`` directive; Sphinx will emit a warning if it
-   finds a file that is not included, because that means that this file will not
-   be reachable through standard navigation.  Use :confval:`unused_docs` to
-   explicitly exclude documents from building, and :confval:`exclude_trees` to
-   exclude whole directories.
-
-   The "master document" (selected by :confval:`master_doc`) is the "root" of
-   the TOC tree hierarchy.  It can be used as the documentation's main page, or
-   as a "full table of contents" if you don't give a ``maxdepth`` option.
-
-   .. versionchanged:: 0.3
-      Added "globbing" option.
-
-   .. versionchanged:: 0.6
-      Added "numbered" and "hidden" options as well as external links and
-      support for "self" references.
-
-   .. versionchanged:: 1.0
-      Added "titlesonly" option.
-
-
-Special names
--------------
-
-Sphinx reserves some document names for its own use; you should not try to
-create documents with these names -- it will cause problems.
-
-The special document names (and pages generated for them) are:
-
-* ``genindex``, ``modindex``, ``search``
-
-  These are used for the general index, the Python module index, and the search
-  page, respectively.
-
-  The general index is populated with entries from modules, all index-generating
-  :ref:`object descriptions <desc-units>`, and from :dir:`index` directives.
-
-  The module index contains one entry per :dir:`module` directive.
-
-  The search page contains a form that uses the generated JSON search index and
-  JavaScript to full-text search the generated documents for search words; it
-  should work on every major browser that supports modern JavaScript.
-
-* every name beginning with ``_``
-
-  Though only few such names are currently used by Sphinx, you should not create
-  documents or document-containing directories with such names.  (Using ``_`` as
-  a prefix for a custom template directory is fine.)
-
-
-.. rubric:: Footnotes
-
-.. [#] The ``maxdepth`` option does not apply to the LaTeX writer, where the
-       whole table of contents will always be presented at the begin of the
-       document, and its depth is controlled by the ``tocdepth`` counter, which
-       you can reset in your :confval:`latex_preamble` config value using
-       e.g. ``\setcounter{tocdepth}{2}``.
-
-.. [#] A note on available globbing syntax: you can use the standard shell
-       constructs ``*``, ``?``, ``[...]`` and ``[!...]`` with the feature that
-       these all don't match slashes.  A double star ``**`` can be used to match
-       any sequence of characters *including* slashes.
 copyright = '2007-2010, Georg Brandl'
 version = sphinx.__released__
 release = version
-
 show_authors = True
 
 html_theme = 'sphinxdoc'

File doc/contents.rst

    :maxdepth: 2
 
    intro
-   concepts
+   tutorial
+   invocation
    rest
    markup/index
    domains
    come through cleanly.
 
 
+.. _usingwith:
+
 Using Sphinx with...
 --------------------
 

File doc/glossary.rst

 
       See :ref:`directives` for more information.
 
+   document name
+      Since reST source files can have different extensions (some people like
+      ``.txt``, some like ``.rst`` -- the extension can be configured with
+      :confval:`source_suffix`) and different OSes have different path separators,
+      Sphinx abstracts them: :dfn:`document names` are always relative to the
+      :term:`source directory`, the extension is stripped, and path separators
+      are converted to slashes.  All values, parameters and such referring to
+      "documents" expect such document names.
+
+      Examples for document names are ``index``, ``library/zipfile``, or
+      ``reference/datamodel/types``.  Note that there is no leading or trailing
+      slash.
+
    domain
       A domain is a collection of markup (reStructuredText :term:`directive`\ s
       and :term:`role`\ s) to describe and link to :term:`object`\ s belonging
       parsing stage, so that successive runs only need to read and parse new and
       changed documents.
 
+   master document
+      The document that contains the root :dir:`toctree` directive.
+
    object
       The basic building block of Sphinx documentation.  Every "object
       directive" (e.g. :dir:`function` or :dir:`object`) creates such a block;

File doc/intro.rst

   markup; it is at `Google Code <http://code.google.com/p/db2rst/>`_.
 
 
+Use with other systems
+----------------------
+
+See the :ref:`pertinent section in the FAQ list <usingwith>`.
+
+
 Prerequisites
 -------------
 
 .. _Pygments: http://pygments.org
 
 
-Setting up the documentation sources
-------------------------------------
+Usage
+-----
 
-The root directory of a documentation collection is called the :dfn:`source
-directory`.  Normally, this directory also contains the Sphinx configuration
-file :file:`conf.py`, but that file can also live in another directory, the
-:dfn:`configuration directory`.
-
-.. versionadded:: 0.3
-   Support for a different configuration directory.
-
-Sphinx comes with a script called :program:`sphinx-quickstart` that sets up a
-source directory and creates a default :file:`conf.py` from a few questions it
-asks you.  Just run ::
-
-   $ sphinx-quickstart
-
-and answer the questions.
-
-
-Running a build
----------------
-
-A build is started with the :program:`sphinx-build` script.  It is called
-like this::
-
-     $ sphinx-build -b latex sourcedir builddir
-
-where *sourcedir* is the :term:`source directory`, and *builddir* is the
-directory in which you want to place the built documentation (it must be an
-existing directory).  The :option:`-b` option selects a builder; in this example
-Sphinx will build LaTeX files.
-
-The :program:`sphinx-build` script has several more options:
-
-**-a**
-   If given, always write all output files.  The default is to only write output
-   files for new and changed source files.  (This may not apply to all
-   builders.)
-
-**-E**
-   Don't use a saved :term:`environment` (the structure caching all
-   cross-references), but rebuild it completely.  The default is to only read
-   and parse source files that are new or have changed since the last run.
-
-**-t** *tag*
-   Define the tag *tag*.  This is relevant for :dir:`only` directives that only
-   include their content if this tag is set.
-
-   .. versionadded:: 0.6
-
-**-d** *path*
-   Since Sphinx has to read and parse all source files before it can write an
-   output file, the parsed source files are cached as "doctree pickles".
-   Normally, these files are put in a directory called :file:`.doctrees` under
-   the build directory; with this option you can select a different cache
-   directory (the doctrees can be shared between all builders).
-
-**-c** *path*
-   Don't look for the :file:`conf.py` in the source directory, but use the given
-   configuration directory instead.  Note that various other files and paths
-   given by configuration values are expected to be relative to the
-   configuration directory, so they will have to be present at this location
-   too.
-
-   .. versionadded:: 0.3
-
-**-C**
-   Don't look for a configuration file; only take options via the ``-D`` option.
-
-   .. versionadded:: 0.5
-
-**-D** *setting=value*
-   Override a configuration value set in the :file:`conf.py` file.  The value
-   must be a string or dictionary value.  For the latter, supply the setting
-   name and key like this: ``-D latex_elements.docclass=scrartcl``.
-
-   .. versionchanged:: 0.6
-      The value can now be a dictionary value.
-
-**-A** *name=value*
-   Make the *name* assigned to *value* in the HTML templates.
-
-**-n**
-   Run in nit-picky mode.  Currently, this generates warnings for all missing
-   references.
-
-**-N**
-   Do not do colored output.  (On Windows, colored output is disabled in any
-   case.)
-
-**-q**
-   Do not output anything on standard output, only write warnings and errors to
-   standard error.
-
-**-Q**
-   Do not output anything on standard output, also suppress warnings.  Only
-   errors are written to standard error.
-
-**-w** *file*
-   Write warnings (and errors) to the given file, in addition to standard error.
-
-**-W**
-   Turn warnings into errors.  This means that the build stops at the first
-   warning and ``sphinx-build`` exits with exit status 1.
-
-**-P**
-   (Useful for debugging only.)  Run the Python debugger, :mod:`pdb`, if an
-   unhandled exception occurs while building.
-
-
-You can also give one or more filenames on the command line after the source and
-build directories.  Sphinx will then try to build only these output files (and
-their dependencies).
+See :doc:`the tutorial <tutorial>` for an introduction.  It also contains links
+to more advanced sections in this manual for the topics it discusses.

File doc/invocation.rst

+.. _invocation:
+
+sphinx-build Invocation
+=======================
+
+A build is started with the :program:`sphinx-build` script.  It is called like
+this::
+
+     $ sphinx-build [options] sourcedir builddir [filenames]
+
+where *sourcedir* is the :term:`source directory`, and *builddir* is the
+directory in which you want to place the built documentation (it must be an
+existing directory).
+
+The :program:`sphinx-build` script has several options:
+
+.. cmdoption:: -b buildername
+
+   Select a builder.  The most common builders are:
+
+   **html**
+      Build HTML pages.  This is the default builder.
+
+   **dirhtml**
+      Build HTML pages, but with a single directory per document.  Makes for
+      prettier URLs (no ``.html``) if served from a webserver.
+
+   **singlehtml**
+      Build a single HTML with the whole content.
+
+   **htmlhelp**, **qthelp**, **devhelp**, **epub**
+      Build HTML files with additional information for building a documentation
+      collection in one of these formats.
+
+   **latex**
+      Build LaTeX sources that can be compiled to a PDF document using
+      :program:`pdflatex`.
+
+   **man**
+      Build manual pages in groff format for UNIX systems.
+
+   **text**
+      Build plain text files.
+
+   **doctest**
+      Run all doctests in the documentation, if the :mod:`~sphinx.ext.doctest`
+      extension is enabled.
+
+   **linkcheck**
+      Check the integrity of all external links.
+
+   See :ref:`builders` for a list of all builders shipped with Sphinx.
+   Extensions can add their own builders.
+
+.. cmdoption:: -a
+
+   If given, always write all output files.  The default is to only write output
+   files for new and changed source files.  (This may not apply to all
+   builders.)
+
+.. cmdoption:: -E
+
+   Don't use a saved :term:`environment` (the structure caching all
+   cross-references), but rebuild it completely.  The default is to only read
+   and parse source files that are new or have changed since the last run.
+
+.. cmdoption:: -t tag
+
+   Define the tag *tag*.  This is relevant for :dir:`only` directives that only
+   include their content if this tag is set.
+
+   .. versionadded:: 0.6
+
+.. cmdoption:: -d path
+
+   Since Sphinx has to read and parse all source files before it can write an
+   output file, the parsed source files are cached as "doctree pickles".
+   Normally, these files are put in a directory called :file:`.doctrees` under
+   the build directory; with this option you can select a different cache
+   directory (the doctrees can be shared between all builders).
+
+.. cmdoption:: -c path
+
+   Don't look for the :file:`conf.py` in the source directory, but use the given
+   configuration directory instead.  Note that various other files and paths
+   given by configuration values are expected to be relative to the
+   configuration directory, so they will have to be present at this location
+   too.
+
+   .. versionadded:: 0.3
+
+.. cmdoption:: -C
+
+   Don't look for a configuration file; only take options via the ``-D`` option.
+
+   .. versionadded:: 0.5
+
+.. cmdoption:: -D setting=value
+
+   Override a configuration value set in the :file:`conf.py` file.  The value
+   must be a string or dictionary value.  For the latter, supply the setting
+   name and key like this: ``-D latex_elements.docclass=scrartcl``.  For boolean
+   values, use ``0`` or ``1`` as the value.
+
+   .. versionchanged:: 0.6
+      The value can now be a dictionary value.
+
+.. cmdoption:: -A name=value
+
+   Make the *name* assigned to *value* in the HTML templates.
+
+   .. versionadded:: 0.5
+
+.. cmdoption:: -n
+
+   Run in nit-picky mode.  Currently, this generates warnings for all missing
+   references.
+
+.. cmdoption:: -N
+
+   Do not emit colored output.  (On Windows, colored output is disabled in any
+   case.)
+
+.. cmdoption:: -q
+
+   Do not output anything on standard output, only write warnings and errors to
+   standard error.
+
+.. cmdoption:: -Q
+
+   Do not output anything on standard output, also suppress warnings.  Only
+   errors are written to standard error.
+
+.. cmdoption:: -w file
+
+   Write warnings (and errors) to the given file, in addition to standard error.
+
+.. cmdoption:: -W
+
+   Turn warnings into errors.  This means that the build stops at the first
+   warning and ``sphinx-build`` exits with exit status 1.
+
+.. cmdoption:: -P
+
+   (Useful for debugging only.)  Run the Python debugger, :mod:`pdb`, if an
+   unhandled exception occurs while building.
+
+
+You can also give one or more filenames on the command line after the source and
+build directories.  Sphinx will then try to build only these output files (and
+their dependencies).
+
+
+Makefile options
+----------------
+
+The :file:`Makefile` and :file:`make.bat` files created by
+:program:`sphinx-quickstart` usually run :program:`sphinx-build` only with the
+:option:`-b` and :option:`-d` options.  However, they support the following
+variables to customize behavior:
+
+.. describe:: PAPER
+
+   The value for :confval:`latex_paper_size`.
+
+.. describe:: SPHINXBUILD
+
+   The command to use instead of ``sphinx-build``.
+
+.. describe:: BUILDDIR
+
+   The build directory to use instead of the one chosen in
+   :program:`sphinx-quickstart`.
+
+.. describe:: SPHINXOPTS
+
+   Additional options for :program:`sphinx-build`.

File doc/markup/index.rst

 
 .. toctree::
 
+   toctree
    desc
    para
    code

File doc/markup/toctree.rst

+.. highlight:: rst
+.. _toctree-directive:
+
+The TOC tree
+============
+
+.. index:: pair: table of; contents
+
+Since reST does not have facilities to interconnect several documents, or split
+documents into multiple output files, Sphinx uses a custom directive to add
+relations between the single files the documentation is made of, as well as
+tables of contents.  The ``toctree`` directive is the central element.
+
+.. directive:: toctree
+
+   This directive inserts a "TOC tree" at the current location, using the
+   individual TOCs (including "sub-TOC trees") of the documents given in the
+   directive body (whose path is relative to the document the directive occurs
+   in).  A numeric ``maxdepth`` option may be given to indicate the depth of the
+   tree; by default, all levels are included. [#]_
+
+   Consider this example (taken from the Python docs' library reference index)::
+
+      .. toctree::
+         :maxdepth: 2
+
+         intro
+         strings
+         datatypes
+         numeric
+         (many more documents listed here)
+
+   This accomplishes two things:
+
+   * Tables of contents from all those documents are inserted, with a maximum
+     depth of two, that means one nested heading.  ``toctree`` directives in
+     those documents are also taken into account.
+   * Sphinx knows that the relative order of the documents ``intro``,
+     ``strings`` and so forth, and it knows that they are children of the shown
+     document, the library index.  From this information it generates "next
+     chapter", "previous chapter" and "parent chapter" links.
+
+   Document titles in the :dir:`toctree` will be automatically read from the
+   title of the referenced document. If that isn't what you want, you can
+   specify an explicit title and target using a similar syntax to reST
+   hyperlinks (and Sphinx's :ref:`cross-referencing syntax <xref-syntax>`). This
+   looks like::
+
+       .. toctree::
+
+          intro
+          All about strings <strings>
+          datatypes
+
+   The second line above will link to the ``strings`` document, but will use the
+   title "All about strings" instead of the title of the ``strings`` document.
+
+   You can also add external links, by giving an HTTP URL instead of a document
+   name.
+
+   If you want to have section numbers even in HTML output, give the toctree a
+   ``numbered`` flag option.  For example::
+
+      .. toctree::
+         :numbered:
+
+         foo
+         bar
+
+   Numbering then starts at the heading of ``foo``.  Sub-toctrees are
+   automatically numbered (don't give the ``numbered`` flag to those).
+
+   If you want only the titles of documents in the tree to show up, not other
+   headings of the same level, you can use the ``titlesonly`` option::
+
+      .. toctree::
+         :titlesonly:
+
+         foo
+         bar
+
+   You can use "globbing" in toctree directives, by giving the ``glob`` flag
+   option.  All entries are then matched against the list of available
+   documents, and matches are inserted into the list alphabetically.  Example::
+
+      .. toctree::
+         :glob:
+
+         intro*
+         recipe/*
+         *
+
+   This includes first all documents whose names start with ``intro``, then all
+   documents in the ``recipe`` folder, then all remaining documents (except the
+   one containing the directive, of course.) [#]_
+
+   The special entry name ``self`` stands for the document containing the
+   toctree directive.  This is useful if you want to generate a "sitemap" from
+   the toctree.
+
+   You can also give a "hidden" option to the directive, like this::
+
+      .. toctree::
+         :hidden:
+
+         doc_1
+         doc_2
+
+   This will still notify Sphinx of the document hierarchy, but not insert links
+   into the document at the location of the directive -- this makes sense if you
+   intend to insert these links yourself, in a different style, or in the HTML
+   sidebar.
+
+   In the end, all documents in the :term:`source directory` (or subdirectories)
+   must occur in some ``toctree`` directive; Sphinx will emit a warning if it
+   finds a file that is not included, because that means that this file will not
+   be reachable through standard navigation.  Use :confval:`unused_docs` to
+   explicitly exclude documents from building, and :confval:`exclude_trees` to
+   exclude whole directories.
+
+   The "master document" (selected by :confval:`master_doc`) is the "root" of
+   the TOC tree hierarchy.  It can be used as the documentation's main page, or
+   as a "full table of contents" if you don't give a ``maxdepth`` option.
+
+   .. versionchanged:: 0.3
+      Added "globbing" option.
+
+   .. versionchanged:: 0.6
+      Added "numbered" and "hidden" options as well as external links and
+      support for "self" references.
+
+   .. versionchanged:: 1.0
+      Added "titlesonly" option.
+
+
+Special names
+-------------
+
+Sphinx reserves some document names for its own use; you should not try to
+create documents with these names -- it will cause problems.
+
+The special document names (and pages generated for them) are:
+
+* ``genindex``, ``modindex``, ``search``
+
+  These are used for the general index, the Python module index, and the search
+  page, respectively.
+
+  The general index is populated with entries from modules, all index-generating
+  :ref:`object descriptions <desc-units>`, and from :dir:`index` directives.
+
+  The module index contains one entry per :dir:`module` directive.
+
+  The search page contains a form that uses the generated JSON search index and
+  JavaScript to full-text search the generated documents for search words; it
+  should work on every major browser that supports modern JavaScript.
+
+* every name beginning with ``_``
+
+  Though only few such names are currently used by Sphinx, you should not create
+  documents or document-containing directories with such names.  (Using ``_`` as
+  a prefix for a custom template directory is fine.)
+
+
+.. rubric:: Footnotes
+
+.. [#] The ``maxdepth`` option does not apply to the LaTeX writer, where the
+       whole table of contents will always be presented at the begin of the
+       document, and its depth is controlled by the ``tocdepth`` counter, which
+       you can reset in your :confval:`latex_preamble` config value using
+       e.g. ``\setcounter{tocdepth}{2}``.
+
+.. [#] A note on available globbing syntax: you can use the standard shell
+       constructs ``*``, ``?``, ``[...]`` and ``[!...]`` with the feature that
+       these all don't match slashes.  A double star ``**`` can be used to match
+       any sequence of characters *including* slashes.

File doc/more.png

Added
New image

File doc/tutorial.rst

+.. highlight:: rst
+
+Sphinx Tutorial -- your first documentation
+===========================================
+
+This document is meant to give an overview of all common tasks while using
+Sphinx.  The green arrows designate "more info" links leading to advanced
+sections about the described task.
+
+
+Setting up the documentation sources
+------------------------------------
+
+The root directory of a documentation collection 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.  Just run ::
+
+   $ sphinx-quickstart
+
+and answer its questions.
+
+
+Adding some content
+-------------------
+
+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 this::
+
+   .. toctree::
+      :maxdepth: 2
+
+You add documents listing them in the *content* of the directive::
+
+   .. toctree::
+      :maxdepth: 2
+
+      intro
+      tutorial
+      ...
+
+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 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 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.)
+
+
+Running the build
+-----------------
+
+A build is started with the :program:`sphinx-build` script.  It is called
+like this::
+
+   $ sphinx-build -b html sourcedir builddir
+
+where *sourcedir* is the :term:`source directory`, and *builddir* is the
+directory in which you want to place the built documentation.  The :option:`-b`
+option selects a builder; in this example Sphinx will build LaTeX files.
+
+However, :program:`sphinx-quickstart` script creates a :file:`Makefile` and a
+:file:`make.bat` which make life even easier for you:  with them you only need
+to run ::
+
+   $ make html
+
+to build HTML docs in the build directory you chose.
+
+|more| See :ref:`invocation` for all options that :program:`sphinx-build`
+supports.
+
+
+Topics to be covered
+--------------------
+
+- Autodoc
+- Domains
+- Basic configuration
+- Selecting a theme
+- Templating
+- Using extensions
+- Writing extensions
+
+
+.. rubric:: Footnotes
+
+.. [#] This is the usual lay-out.  However, :file:`conf.py` can also live in
+       another directory, the :term:`configuration directory`.  See
+       :ref:`invocation`.
+
+.. |more| image:: more.png
+          :align: middle
+          :alt: more info