[Python-checkins] r67158 - in python/trunk/Doc/documenting: index.rst markup.rst rest.rst sphinx.rst
georg.brandl
python-checkins at python.org
Sat Nov 8 12:48:21 CET 2008
Author: georg.brandl
Date: Sat Nov 8 12:48:20 2008
New Revision: 67158
Log:
Update "Documenting" a bit. Concentrate on Python-specifics.
Removed:
python/trunk/Doc/documenting/sphinx.rst
Modified:
python/trunk/Doc/documenting/index.rst
python/trunk/Doc/documenting/markup.rst
python/trunk/Doc/documenting/rest.rst
Modified: python/trunk/Doc/documenting/index.rst
==============================================================================
--- python/trunk/Doc/documenting/index.rst (original)
+++ python/trunk/Doc/documenting/index.rst Sat Nov 8 12:48:20 2008
@@ -8,7 +8,7 @@
The Python language has a substantial body of documentation, much of it
contributed by various authors. The markup used for the Python documentation is
`reStructuredText`_, developed by the `docutils`_ project, amended by custom
-directives and using a toolset named *Sphinx* to postprocess the HTML output.
+directives and using a toolset named `Sphinx`_ to postprocess the HTML output.
This document describes the style guide for our documentation, the custom
reStructuredText markup introduced to support Python documentation and how it
@@ -16,6 +16,7 @@
.. _reStructuredText: http://docutils.sf.net/rst.html
.. _docutils: http://docutils.sf.net/
+.. _Sphinx: http://sphinx.pocoo.org/
If you're interested in contributing to Python's documentation, there's no need
to write reStructuredText if you're not so inclined; plain text contributions
@@ -28,7 +29,3 @@
rest.rst
markup.rst
fromlatex.rst
- sphinx.rst
-
-.. XXX add credits, thanks etc.
-
Modified: python/trunk/Doc/documenting/markup.rst
==============================================================================
--- python/trunk/Doc/documenting/markup.rst (original)
+++ python/trunk/Doc/documenting/markup.rst Sat Nov 8 12:48:20 2008
@@ -8,24 +8,11 @@
Documentation for "standard" reST constructs is not included here, though
they are used in the Python documentation.
-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:
+.. note::
-``nocomments``
- If set, the web application won't display a comment form for a page generated
- from this source file.
+ This is just an overview of Sphinx' extended markup capabilities; full
+ coverage can be found in `its own documentation
+ <http://sphinx.pocoo.org/contents.html>`_.
Meta-information markup
@@ -88,7 +75,6 @@
authors of the module code, just like ``sectionauthor`` names the author(s)
of a piece of documentation. It too does not result in any output currently.
-
.. note::
It is important to make the section title of a module-describing file
@@ -272,7 +258,7 @@
This language is used until the next ``highlightlang`` directive is
encountered.
-* The valid values for the highlighting language are:
+* The values normally used for the highlighting language are:
* ``python`` (the default)
* ``c``
Modified: python/trunk/Doc/documenting/rest.rst
==============================================================================
--- python/trunk/Doc/documenting/rest.rst (original)
+++ python/trunk/Doc/documenting/rest.rst Sat Nov 8 12:48:20 2008
@@ -67,12 +67,6 @@
#. This is a numbered list.
#. It has two items too.
-Note that Sphinx disables the use of enumerated lists introduced by alphabetic
-or roman numerals, such as ::
-
- A. First item
- B. Second item
-
Nested lists are possible, but be aware that they must be separated from the
parent list items by blank lines::
@@ -247,5 +241,3 @@
* **Separation of inline markup:** As said above, inline markup spans must be
separated from the surrounding text by non-word characters, you have to use
an escaped space to get around that.
-
-.. XXX more?
Deleted: python/trunk/Doc/documenting/sphinx.rst
==============================================================================
--- python/trunk/Doc/documenting/sphinx.rst Sat Nov 8 12:48:20 2008
+++ (empty file)
@@ -1,76 +0,0 @@
-.. highlightlang:: rest
-
-The Sphinx build system
-=======================
-
-.. XXX: intro...
-
-.. _doc-build-config:
-
-The build configuration file
-----------------------------
-
-The documentation root, that is the ``Doc`` subdirectory of the source
-distribution, contains a file named ``conf.py``. This file is called the "build
-configuration file", and it contains several variables that are read and used
-during a build run.
-
-These variables are:
-
-version : string
- A string that is used as a replacement for the ``|version|`` reST
- substitution. It should be the Python version the documentation refers to.
- This consists only of the major and minor version parts, e.g. ``2.5``, even
- for version 2.5.1.
-
-release : string
- A string that is used as a replacement for the ``|release|`` reST
- substitution. It should be the full version string including
- alpha/beta/release candidate tags, e.g. ``2.5.2b3``.
-
-Both ``release`` and ``version`` can be ``'auto'``, which means that they are
-determined at runtime from the ``Include/patchlevel.h`` file, if a complete
-Python source distribution can be found, or else from the interpreter running
-Sphinx.
-
-today_fmt : string
- A ``strftime`` format that is used to format a replacement for the
- ``|today|`` reST substitution.
-
-today : string
- A string that can contain a date that should be written to the documentation
- output literally. If this is nonzero, it is used instead of
- ``strftime(today_fmt)``.
-
-unused_files : list of strings
- A list of reST filenames that are to be disregarded during building. This
- could be docs for temporarily disabled modules or documentation that's not
- yet ready for public consumption.
-
-add_function_parentheses : bool
- If true, ``()`` will be appended to the content of ``:func:``, ``:meth:`` and
- ``:cfunc:`` cross-references.
-
-add_module_names : bool
- If true, the current module name will be prepended to all description unit
- titles (such as ``.. function::``).
-
-Builder-specific variables
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-html_download_base_url : string
- The base URL for download links on the download page.
-
-html_last_updated_fmt : string
- If this is not an empty string, it will be given to ``time.strftime()`` and
- written to each generated output file after "last updated on:".
-
-html_use_smartypants : bool
- If true, use SmartyPants to convert quotes and dashes to the typographically
- correct entities.
-
-latex_paper_size : "letter" or "a4"
- The paper size option for the LaTeX document class.
-
-latex_font_size : "10pt", "11pt" or "12pt"
- The font size option for the LaTeX document class.
\ No newline at end of file
More information about the Python-checkins
mailing list