doc: Add "field-lists" doc to restructuredtext section

These are very poorly documented at present, especially given their
power and use in basically all non-Napoleon based Python documentation.

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

doc/markup/misc.rst

@@ -3,41 +3,6 @@
 Miscellaneous markup
 ====================
 
-.. _metadata:
-
-File-wide metadata
-------------------
-
-reST has the concept of "field lists"; these are a sequence of fields marked up
-like this::
-
-   :fieldname: Field content
-
-A field list near the top of a file is parsed by docutils as the "docinfo"
-which is normally used to record the author, date of publication and other
-metadata.  *In Sphinx*, a field list preceding any other markup is moved from
-the docinfo to the Sphinx environment as document metadata and is not displayed
-in the output; a field list appearing after the document title will be part of
-the docinfo as normal and will be displayed in the output.
-
-At the moment, these metadata fields are recognized:
-
-``tocdepth``
-   The maximum depth for a table of contents of this file.
-
-   .. versionadded:: 0.4
-
-``nocomments``
-   If set, the web application won't display a comment form for a page generated
-   from this source file.
-
-``orphan``
-   If set, warnings about this file not being included in any toctree will be
-   suppressed.
-
-   .. versionadded:: 1.0
-
-
 Meta-information markup
 -----------------------
 

doc/usage/restructuredtext/basics.rst

@@ -1,4 +1,4 @@
-.. highlightlang:: rest
+.. highlightlang:: rst
 
 =======================
 reStructuredText Primer
@@ -105,7 +105,8 @@ Line blocks (:duref:`ref <line-blocks>`) are a way of preserving line breaks::
 
 There are also several more special blocks available:
 
-* field lists (:duref:`ref <field-lists>`)
+* field lists (:duref:`ref <field-lists>`, with caveats noted in
+  :ref:`rst-field-lists`)
 * option lists (:duref:`ref <option-lists>`)
 * quoted literal blocks (:duref:`ref <quoted-literal-blocks>`)
 * doctest blocks (:duref:`ref <doctest-blocks>`)
@@ -235,6 +236,32 @@ documentation), and use a deeper nesting level, but keep in mind that most
 target formats (HTML, LaTeX) have a limited supported nesting depth.
 
 
+.. _rst-field-lists:
+
+Field Lists
+-----------
+
+Field lists (:duref:`ref <field-lists>`) are sequences of fields marked up like
+this::
+
+   :fieldname: Field content
+
+They are commonly used in Python documentation::
+
+    def my_function(my_arg, my_other_arg):
+        """A function just for me.
+
+        :param my_arg: The first of my arguments.
+        :param my_other_arg: The second of my arguments.
+
+        :returns: A message (just for me, of course).
+        """
+
+Sphinx extends standard docutils behavior and intercepts field lists specified
+at the beginning of documents.  Refer to :doc:`field-lists` for more
+information.
+
+
 .. TODO This ref should be 'rst-roles', but that already exists. Rename the
 .. other ones
 

doc/usage/restructuredtext/field-lists.rst

@@ -0,0 +1,47 @@
+.. highlightlang:: rst
+
+===========
+Field Lists
+===========
+
+:ref:`As previously discussed <rst-field-lists>`, field lists are sequences of
+fields marked up like this::
+
+    :fieldname: Field content
+
+Sphinx provides custom behavior for bibliographic fields compared to docutils.
+
+.. _metadata:
+
+File-wide metadata
+------------------
+
+A field list near the top of a file is normally parsed by docutils as the
+*docinfo* which is generally used to record the author, date of publication and
+other metadata.  However, in Sphinx, a field list preceding any other markup is
+moved from the *docinfo* to the Sphinx environment as document metadata and is
+not displayed in the output; a field list appearing after the document title
+will be part of the *docinfo* as normal and will be displayed in the output.
+
+At the moment, these metadata fields are recognized:
+
+``tocdepth``
+   The maximum depth for a table of contents of this file. ::
+
+       :tocdepth: 2
+
+   .. versionadded:: 0.4
+
+``nocomments``
+   If set, the web application won't display a comment form for a page
+   generated from this source file. ::
+
+       :nocomments:
+
+``orphan``
+   If set, warnings about this file not being included in any toctree will be
+   suppressed. ::
+
+       :orphan:
+
+   .. versionadded:: 1.0

doc/usage/restructuredtext/index.rst

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