mirror of https://github.com/python/cpython
Update "Documenting" a bit. Concentrate on Python-specifics.
This commit is contained in:
Georg Brandl
parent
012a1ff935
commit
bce1f5f742
|
|
@ -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 @@ should be used, as well as the Sphinx build system.
|
|||
|
||||
.. _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 @@ are more than welcome as well.
|
|||
rest.rst
|
||||
markup.rst
|
||||
fromlatex.rst
|
||||
sphinx.rst
|
||||
|
||||
.. XXX add credits, thanks etc.
|
||||
|
||||
|
|
|
|||
|
|
@ -8,24 +8,11 @@ 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.
|
||||
|
||||
File-wide metadata
|
||||
------------------
|
||||
.. note::
|
||||
|
||||
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.
|
||||
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 @@ As you can see, the module-specific markup consists of two directives, the
|
|||
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 @@ Syntax highlighting is handled in a smart way:
|
|||
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``
|
||||
|
|
|
|||
|
|
@ -67,12 +67,6 @@ autonumbered using a ``#`` sign::
|
|||
#. 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 @@ There are some problems one commonly runs into while authoring reST documents:
|
|||
* **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?
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
Loading…
Reference in New Issue