diff --git a/Doc-26/documenting/markup.rst b/Doc-26/documenting/markup.rst index 1470d2b76..4f63ac5fd 100644 --- a/Doc-26/documenting/markup.rst +++ b/Doc-26/documenting/markup.rst @@ -8,7 +8,25 @@ markup. This section contains the reference material for these facilities. Documentation for "standard" reST constructs is not included here, though they are used in the Python documentation. -.. XXX: file-wide metadata +File-wide metadata +------------------ + +reST has the concept of "field lists"; these are a sequence of fields marked up +like this:: + + :Field name: Field content + +A field list at the very top of a file is parsed as the "docinfo", which in +normal documents can be used to record the author, date of publication and +other metadata. In Sphinx, the docinfo is used as metadata, too, but not +displayed in the output. + +At the moment, only one metadata field is recognized: + +``nocomments`` + If set, the web application won't display a comment form for a page generated + from this source file. + Meta-information markup ----------------------- @@ -265,9 +283,7 @@ Inline markup As said before, Sphinx uses interpreted text roles to insert semantic markup in documents. -The default role is ``var``, as that was one of the most common macros used in -the old LaTeX docs. That means that you can use ```var``` to refer to a -variable named "var". +Variable names are an exception, they should be marked simply with ``*var*``. For all other roles, you have to write ``:rolename:`content```. @@ -488,7 +504,7 @@ Cross-linking markup -------------------- To support cross-referencing to arbitrary sections in the documentation, the -standard reST labels are "abused" a bit: Every label must precede a section +standard reST labels are "abused" a bit: Every label must precede a section title; and every label name must be unique throughout the entire documentation source. diff --git a/Doc-26/documenting/rest.rst b/Doc-26/documenting/rest.rst index eb2ba3e81..93eb2fd34 100644 --- a/Doc-26/documenting/rest.rst +++ b/Doc-26/documenting/rest.rst @@ -4,10 +4,9 @@ reStructuredText Primer ======================= This section is a brief introduction to reStructuredText (reST) concepts and -syntax, intended to provide authors with enough information to author -documents productively. -Since reST was designed to be a simple, unobtrusive markup language, this will -not take too long. +syntax, intended to provide authors with enough information to author documents +productively. Since reST was designed to be a simple, unobtrusive markup +language, this will not take too long. .. seealso:: @@ -18,12 +17,13 @@ not take too long. Paragraphs ---------- -The paragraph is the most basic block in a reST document. -Paragraphs are simply chunks of text -separated by one or more blank lines. As in Python, indentation is significant -in reST, so all lines of the same paragraph must be left-aligned +The paragraph is the most basic block in a reST document. Paragraphs are simply +chunks of text separated by one or more blank lines. As in Python, indentation +is significant in reST, so all lines of the same paragraph must be left-aligned to the same level of indentation. +The Python docs use an indentation of 3 spaces. + Inline markup ------------- diff --git a/Doc-26/documenting/sphinx.rst b/Doc-26/documenting/sphinx.rst index 582bdbf79..85e8b5e32 100644 --- a/Doc-26/documenting/sphinx.rst +++ b/Doc-26/documenting/sphinx.rst @@ -3,7 +3,7 @@ The Sphinx build system ======================= -XXX: intro... +.. XXX: intro... .. _doc-build-config: diff --git a/Doc-3k/documenting/markup.rst b/Doc-3k/documenting/markup.rst index 1470d2b76..4f63ac5fd 100644 --- a/Doc-3k/documenting/markup.rst +++ b/Doc-3k/documenting/markup.rst @@ -8,7 +8,25 @@ markup. This section contains the reference material for these facilities. Documentation for "standard" reST constructs is not included here, though they are used in the Python documentation. -.. XXX: file-wide metadata +File-wide metadata +------------------ + +reST has the concept of "field lists"; these are a sequence of fields marked up +like this:: + + :Field name: Field content + +A field list at the very top of a file is parsed as the "docinfo", which in +normal documents can be used to record the author, date of publication and +other metadata. In Sphinx, the docinfo is used as metadata, too, but not +displayed in the output. + +At the moment, only one metadata field is recognized: + +``nocomments`` + If set, the web application won't display a comment form for a page generated + from this source file. + Meta-information markup ----------------------- @@ -265,9 +283,7 @@ Inline markup As said before, Sphinx uses interpreted text roles to insert semantic markup in documents. -The default role is ``var``, as that was one of the most common macros used in -the old LaTeX docs. That means that you can use ```var``` to refer to a -variable named "var". +Variable names are an exception, they should be marked simply with ``*var*``. For all other roles, you have to write ``:rolename:`content```. @@ -488,7 +504,7 @@ Cross-linking markup -------------------- To support cross-referencing to arbitrary sections in the documentation, the -standard reST labels are "abused" a bit: Every label must precede a section +standard reST labels are "abused" a bit: Every label must precede a section title; and every label name must be unique throughout the entire documentation source. diff --git a/Doc-3k/documenting/rest.rst b/Doc-3k/documenting/rest.rst index eb2ba3e81..93eb2fd34 100644 --- a/Doc-3k/documenting/rest.rst +++ b/Doc-3k/documenting/rest.rst @@ -4,10 +4,9 @@ reStructuredText Primer ======================= This section is a brief introduction to reStructuredText (reST) concepts and -syntax, intended to provide authors with enough information to author -documents productively. -Since reST was designed to be a simple, unobtrusive markup language, this will -not take too long. +syntax, intended to provide authors with enough information to author documents +productively. Since reST was designed to be a simple, unobtrusive markup +language, this will not take too long. .. seealso:: @@ -18,12 +17,13 @@ not take too long. Paragraphs ---------- -The paragraph is the most basic block in a reST document. -Paragraphs are simply chunks of text -separated by one or more blank lines. As in Python, indentation is significant -in reST, so all lines of the same paragraph must be left-aligned +The paragraph is the most basic block in a reST document. Paragraphs are simply +chunks of text separated by one or more blank lines. As in Python, indentation +is significant in reST, so all lines of the same paragraph must be left-aligned to the same level of indentation. +The Python docs use an indentation of 3 spaces. + Inline markup ------------- diff --git a/Doc-3k/documenting/sphinx.rst b/Doc-3k/documenting/sphinx.rst index 582bdbf79..85e8b5e32 100644 --- a/Doc-3k/documenting/sphinx.rst +++ b/Doc-3k/documenting/sphinx.rst @@ -3,7 +3,7 @@ The Sphinx build system ======================= -XXX: intro... +.. XXX: intro... .. _doc-build-config: