From 08ff8160b8a6d9879430710e51a905d843ec66a3 Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Fri, 3 Nov 2017 14:35:20 +0000 Subject: [PATCH] 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 --- doc/markup/misc.rst | 35 ---------------- doc/usage/restructuredtext/basics.rst | 31 +++++++++++++- doc/usage/restructuredtext/field-lists.rst | 47 ++++++++++++++++++++++ doc/usage/restructuredtext/index.rst | 1 + 4 files changed, 77 insertions(+), 37 deletions(-) create mode 100644 doc/usage/restructuredtext/field-lists.rst diff --git a/doc/markup/misc.rst b/doc/markup/misc.rst index afff2ae27..a4fbce5a0 100644 --- a/doc/markup/misc.rst +++ b/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 ----------------------- diff --git a/doc/usage/restructuredtext/basics.rst b/doc/usage/restructuredtext/basics.rst index de18f7f4d..0bfb311c1 100644 --- a/doc/usage/restructuredtext/basics.rst +++ b/doc/usage/restructuredtext/basics.rst @@ -1,4 +1,4 @@ -.. highlightlang:: rest +.. highlightlang:: rst ======================= reStructuredText Primer @@ -105,7 +105,8 @@ Line blocks (:duref:`ref `) are a way of preserving line breaks:: There are also several more special blocks available: -* field lists (:duref:`ref `) +* field lists (:duref:`ref `, with caveats noted in + :ref:`rst-field-lists`) * option lists (:duref:`ref `) * quoted literal blocks (:duref:`ref `) * doctest blocks (:duref:`ref `) @@ -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 `) 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 diff --git a/doc/usage/restructuredtext/field-lists.rst b/doc/usage/restructuredtext/field-lists.rst new file mode 100644 index 000000000..10ded3ea4 --- /dev/null +++ b/doc/usage/restructuredtext/field-lists.rst @@ -0,0 +1,47 @@ +.. highlightlang:: rst + +=========== +Field Lists +=========== + +:ref:`As previously discussed `, 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 diff --git a/doc/usage/restructuredtext/index.rst b/doc/usage/restructuredtext/index.rst index 8b7b75a1a..5ff872f0d 100644 --- a/doc/usage/restructuredtext/index.rst +++ b/doc/usage/restructuredtext/index.rst @@ -17,3 +17,4 @@ __ http://docutils.sourceforge.net/rst.html basics roles + field-lists