doc: Add "directives" doc to restructuredtext section

There's simply no need to artificially divide up the documentation on
directives into multiple, hard-to-navigate documents. Gather all
documentation for directives into one easy-to-reference guide, starting
with the former 'toctree' document. There are no changes to the content.

Signed-off-by: Stephen Finucane <stephen@that.guru>

doc/usage/restructuredtext/basics.rst

@@ -303,7 +303,7 @@ normal paragraphs.  This may all sound a bit complicated, but it is intuitive
 enough when you write it.)
 
 
-.. _directives:
+.. _rst-directives:
 
 Directives
 ----------
@@ -371,7 +371,7 @@ Docutils supports the following directives:
    Do *not* use the directives :dudir:`sectnum`, :dudir:`header` and
    :dudir:`footer`.
 
-Directives added by Sphinx are described in :ref:`sphinxmarkup`.
+Directives added by Sphinx are described in :doc:`directives`.
 
 Basically, a directive consists of a name, arguments, options and content.
 (Keep this terminology in mind, it is used in the next chapter describing

doc/usage/restructuredtext/directives.rst

@@ -0,0 +1,265 @@
+.. highlight:: rst
+
+==========
+Directives
+==========
+
+:ref:`As previously discussed <rst-directives>`, a directive is a generic block
+of explicit markup. While Docutils provides a number of directives, Sphinx
+provides many more and uses directives as one of the primary extension
+mechanisms.
+
+.. seealso::
+
+   Refer to the :ref:`reStructuredText Primer <rst-directives>` for an overview
+   of the directives provided by Docutils.
+
+
+.. _toctree-directive:
+
+Table of contents
+-----------------
+
+.. 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.
+
+.. note::
+
+   Simple "inclusion" of one file in another can be done with the
+   :dudir:`include` directive.
+
+.. note::
+
+   For local tables of contents, use the standard reST :dudir:`contents
+   directive <table-of-contents>`.
+
+.. rst: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.  Relative document names (not beginning with a slash) are
+   relative to the document the directive occurs in, absolute names are relative
+   to the source directory.  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 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.
+
+   **Entries**
+
+   Document titles in the :rst: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.
+
+   **Section numbering**
+
+   If you want to have section numbers even in HTML output, give the
+   **toplevel** toctree a ``numbered`` 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).
+
+   Numbering up to a specific depth is also possible, by giving the depth as a
+   numeric argument to ``numbered``.
+
+   **Additional options**
+
+   You can use ``caption`` option to provide a toctree caption and you can use
+   ``name`` option to provide implicit target name that can be referenced by
+   using :rst:role:`ref`::
+
+      .. toctree::
+         :caption: Table of Contents
+         :name: mastertoc
+
+         foo
+
+   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 use the ``reversed`` flag option to reverse the order of the entries
+   in the list. This can be useful when using the ``glob`` flag option to
+   reverse the ordering of the files.  Example::
+
+      .. toctree::
+         :glob:
+         :reversed:
+
+         recipe/*
+
+   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 cases where you want to have only one top-level toctree and hide all other
+   lower level toctrees you can add the "includehidden" option to the top-level
+   toctree entry::
+
+      .. toctree::
+         :includehidden:
+
+         doc_1
+         doc_2
+
+   All other toctree entries can then be eliminated by the "hidden" option.
+
+   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:`exclude_patterns` to explicitly exclude documents or
+   directories from building completely.  Use :ref:`the "orphan" metadata
+   <metadata>` to let a document be built, but notify Sphinx that it is not
+   reachable via a toctree.
+
+   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.
+
+   .. versionchanged:: 1.1
+      Added numeric argument to "numbered".
+
+   .. versionchanged:: 1.2
+      Added "includehidden" option.
+
+   .. versionchanged:: 1.3
+      Added "caption" and "name" 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 <basic-domain-markup>`, and from
+  :rst:dir:`index` directives.
+
+  The Python module index contains one entry per :rst:dir:`py: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.)
+
+.. warning::
+
+   Be careful with unusual characters in filenames.  Some formats may interpret
+   these characters in unexpected ways:
+
+   * Do not use the colon ``:`` for HTML based formats.  Links to other parts
+     may not work.
+
+   * Do not use the plus ``+`` for the ePub format.  Some resources may not be
+     found.
+
+
+.. rubric:: Footnotes
+
+.. [#] The LaTeX writer only refers the ``maxdepth`` option of first toctree
+       directive in the document.
+
+.. [#] 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.

doc/usage/restructuredtext/index.rst

@@ -17,4 +17,5 @@ __ http://docutils.sourceforge.net/rst.html
 
    basics
    roles
+   directives
    field-lists