Anonymous avatar Anonymous committed abf94b0

Write a bit more in "Documenting".

Comments (0)

Files changed (6)

Doc-26/documenting/markup.rst

 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
 -----------------------
 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```.
 
 --------------------
 
 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.
 

Doc-26/documenting/rest.rst

 =======================
 
 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::
 
 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
 -------------

Doc-26/documenting/sphinx.rst

 The Sphinx build system
 =======================
 
-XXX: intro...
+.. XXX: intro...
 
 .. _doc-build-config:
 

Doc-3k/documenting/markup.rst

 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
 -----------------------
 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```.
 
 --------------------
 
 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.
 

Doc-3k/documenting/rest.rst

 =======================
 
 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::
 
 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
 -------------

Doc-3k/documenting/sphinx.rst

 The Sphinx build system
 =======================
 
-XXX: intro...
+.. XXX: intro...
 
 .. _doc-build-config:
 
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.