[Python-checkins] r56700 - in doctools/trunk: Doc-26/documenting/markup.rst Doc-26/documenting/rest.rst Doc-26/documenting/sphinx.rst Doc-3k/documenting/markup.rst Doc-3k/documenting/rest.rst Doc-3k/documenting/sphinx.rst
georg.brandl
python-checkins at python.org
Fri Aug 3 13:56:23 CEST 2007
Author: georg.brandl
Date: Fri Aug 3 13:56:22 2007
New Revision: 56700
Modified:
doctools/trunk/Doc-26/documenting/markup.rst
doctools/trunk/Doc-26/documenting/rest.rst
doctools/trunk/Doc-26/documenting/sphinx.rst
doctools/trunk/Doc-3k/documenting/markup.rst
doctools/trunk/Doc-3k/documenting/rest.rst
doctools/trunk/Doc-3k/documenting/sphinx.rst
Log:
Write a bit more in "Documenting".
Modified: doctools/trunk/Doc-26/documenting/markup.rst
==============================================================================
--- doctools/trunk/Doc-26/documenting/markup.rst (original)
+++ doctools/trunk/Doc-26/documenting/markup.rst Fri Aug 3 13:56:22 2007
@@ -8,7 +8,25 @@
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 @@
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 @@
--------------------
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.
Modified: doctools/trunk/Doc-26/documenting/rest.rst
==============================================================================
--- doctools/trunk/Doc-26/documenting/rest.rst (original)
+++ doctools/trunk/Doc-26/documenting/rest.rst Fri Aug 3 13:56:22 2007
@@ -4,10 +4,9 @@
=======================
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 @@
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
-------------
Modified: doctools/trunk/Doc-26/documenting/sphinx.rst
==============================================================================
--- doctools/trunk/Doc-26/documenting/sphinx.rst (original)
+++ doctools/trunk/Doc-26/documenting/sphinx.rst Fri Aug 3 13:56:22 2007
@@ -3,7 +3,7 @@
The Sphinx build system
=======================
-XXX: intro...
+.. XXX: intro...
.. _doc-build-config:
Modified: doctools/trunk/Doc-3k/documenting/markup.rst
==============================================================================
--- doctools/trunk/Doc-3k/documenting/markup.rst (original)
+++ doctools/trunk/Doc-3k/documenting/markup.rst Fri Aug 3 13:56:22 2007
@@ -8,7 +8,25 @@
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 @@
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 @@
--------------------
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.
Modified: doctools/trunk/Doc-3k/documenting/rest.rst
==============================================================================
--- doctools/trunk/Doc-3k/documenting/rest.rst (original)
+++ doctools/trunk/Doc-3k/documenting/rest.rst Fri Aug 3 13:56:22 2007
@@ -4,10 +4,9 @@
=======================
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 @@
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
-------------
Modified: doctools/trunk/Doc-3k/documenting/sphinx.rst
==============================================================================
--- doctools/trunk/Doc-3k/documenting/sphinx.rst (original)
+++ doctools/trunk/Doc-3k/documenting/sphinx.rst Fri Aug 3 13:56:22 2007
@@ -3,7 +3,7 @@
The Sphinx build system
=======================
-XXX: intro...
+.. XXX: intro...
.. _doc-build-config:
More information about the Python-checkins
mailing list