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/glossary.rst

@@ -32,7 +32,7 @@ Glossary
 
             Content of the directive.
 
-      See :ref:`directives` for more information.
+      See :ref:`rst-directives` for more information.
 
    document name
       Since reST source files can have different extensions (some people like

doc/markup/index.rst

@@ -1,5 +1,3 @@
-.. _sphinxmarkup:
-
 Sphinx Markup Constructs
 ========================
 
@@ -9,7 +7,6 @@ facilities.
 
 .. toctree::
 
-   toctree
    para
    code
    misc

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

@@ -1,4 +1,20 @@
 .. 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
@@ -237,6 +253,7 @@ The special document names (and pages generated for them) are:
    * 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

doc/usage/restructuredtext/index.rst

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