[Python-checkins] r61355 - in doctools/trunk/doc: builders.rst ext ext/api.rst ext/autodoc.rst ext/coverage.rst ext/doctest.rst ext/ifconfig.rst ext/refcounting.rst extensions.rst intro.rst templating.rst
georg.brandl
python-checkins at python.org
Wed Mar 12 22:37:53 CET 2008
Author: georg.brandl
Date: Wed Mar 12 22:37:22 2008
New Revision: 61355
Added:
doctools/trunk/doc/ext/
doctools/trunk/doc/ext/api.rst
doctools/trunk/doc/ext/autodoc.rst
doctools/trunk/doc/ext/coverage.rst
doctools/trunk/doc/ext/doctest.rst
doctools/trunk/doc/ext/ifconfig.rst
doctools/trunk/doc/ext/refcounting.rst
Modified:
doctools/trunk/doc/builders.rst
doctools/trunk/doc/extensions.rst
doctools/trunk/doc/intro.rst
doctools/trunk/doc/templating.rst
Log:
Some more documentation.
Modified: doctools/trunk/doc/builders.rst
==============================================================================
--- doctools/trunk/doc/builders.rst (original)
+++ doctools/trunk/doc/builders.rst Wed Mar 12 22:37:22 2008
@@ -7,3 +7,17 @@
:synopsis: Available built-in builder classes.
+.. class:: Builder
+
+.. class:: StandaloneHTMLBuilder
+
+.. class:: WebHTMLBuilder
+
+.. class:: HTMLHelpBuilder
+
+.. class:: LaTeXBuilder
+
+.. class:: ChangesBuilder
+
+.. class:: CheckExternalLinksBuilder
+
Added: doctools/trunk/doc/ext/api.rst
==============================================================================
--- (empty file)
+++ doctools/trunk/doc/ext/api.rst Wed Mar 12 22:37:22 2008
@@ -0,0 +1,96 @@
+Extension API
+=============
+
+Each Sphinx extension is a Python module with at least a :func:`setup` function.
+This function is called at initialization time with one argument, the
+application object representing the Sphinx process. This application object has
+the following public API:
+
+.. method:: Application.add_builder(builder)
+
+ Register a new builder. *builder* must be a class that inherits from
+ :class:`~sphinx.builder.Builder`.
+
+.. method:: Application.add_config_value(name, default, rebuild_env)
+
+ Register a configuration value. This is necessary for Sphinx to recognize
+ new values and set default values accordingly. The *name* should be prefixed
+ with the extension name, to avoid clashes. The *default* value can be any
+ Python object. The boolean value *rebuild_env* must be ``True`` if a change
+ in the setting only takes effect when a document is parsed -- this means that
+ the whole environment must be rebuilt.
+
+.. method:: Application.add_event(name)
+
+ Register an event called *name*.
+
+.. method:: Application.add_node(node)
+
+ Register a Docutils node class. This is necessary for Docutils internals.
+ It may also be used in the future to validate nodes in the parsed documents.
+
+.. method:: Application.add_directive(name, cls, content, arguments, **options)
+
+ Register a Docutils directive. *name* must be the prospective directive
+ name, *func* the directive function (see the Docutils documentation - XXX
+ ref) for details about the signature and return value. *content*,
+ *arguments* and *options* are set as attributes on the function and determine
+ whether the directive has content, arguments and options, respectively. For
+ their exact meaning, please consult the Docutils documentation.
+
+.. method:: Application.add_role(name, role)
+
+ Register a Docutils role. *name* must be the role name that occurs in the
+ source, *role* the role function (see the Docutils documentation on details).
+
+.. method:: Application.add_description_unit(directivename, rolename, indexdesc='', parse_node=None)
+
+ XXX
+
+.. method:: Application.connect(event, callback)
+
+ Register *callback* to be called when *event* is emitted. For details on
+ available core events and the arguments of callback functions, please see
+ :ref:`events`.
+
+ The method returns a "listener ID" that can be used as an argument to
+ :meth:`disconnect`.
+
+.. method:: Application.disconnect(listener_id)
+
+ Unregister callback *listener_id*.
+
+.. method:: Application.emit(event, *arguments)
+
+ Emit *event* and pass *arguments* to the callback functions. Do not emit
+ core Sphinx events in extensions!
+
+
+.. exception:: ExtensionError
+
+ All these functions raise this exception if something went wrong with the
+ extension API.
+
+Examples of using the Sphinx extension API can be seen in the :mod:`sphinx.ext`
+package.
+
+
+.. _events:
+
+Sphinx core events
+------------------
+
+These events are known to the core:
+
+====================== =================================== =========
+Event name Emitted when Arguments
+====================== =================================== =========
+``'builder-inited'`` the builder object has been created -none-
+``'doctree-read'`` a doctree has been parsed and read *doctree*
+ by the environment, and is about to
+ be pickled
+``'doctree-resolved'`` a doctree has been "resolved" by *doctree*, *docname*
+ the environment, that is, all
+ references and TOCs have been
+ inserted
+====================== =================================== =========
Added: doctools/trunk/doc/ext/autodoc.rst
==============================================================================
--- (empty file)
+++ doctools/trunk/doc/ext/autodoc.rst Wed Mar 12 22:37:22 2008
@@ -0,0 +1,5 @@
+:mod:`sphinx.ext.autodoc` -- Include documentation from docstrings
+==================================================================
+
+.. module:: sphinx.ext.autodoc
+ :synopsis: Include documentation from docstrings.
Added: doctools/trunk/doc/ext/coverage.rst
==============================================================================
--- (empty file)
+++ doctools/trunk/doc/ext/coverage.rst Wed Mar 12 22:37:22 2008
@@ -0,0 +1,29 @@
+:mod:`sphinx.ext.coverage` -- Collect doc coverage stats
+========================================================
+
+.. module:: sphinx.ext.coverage
+ :synopsis: Check Python modules and C API for coverage in the documentation.
+
+
+This extension features one additional builder, the :class:`CoverageBuilder`.
+
+.. class:: CoverageBuilder
+
+ To use this builder, activate the coverage extension in your configuration
+ file and give ``-b coverage`` on the command line.
+
+
+Several new configuration values can be used to specify what the builder
+should check:
+
+.. confval:: coverage_ignore_modules
+
+.. confval:: coverage_ignore_functions
+
+.. confval:: coverage_ignore_classes
+
+.. confval:: coverage_c_path
+
+.. confval:: coverage_c_regexes
+
+.. confval:: coverage_ignore_c_items
Added: doctools/trunk/doc/ext/doctest.rst
==============================================================================
--- (empty file)
+++ doctools/trunk/doc/ext/doctest.rst Wed Mar 12 22:37:22 2008
@@ -0,0 +1,5 @@
+:mod:`sphinx.ext.doctest` -- Test snippets in the documentation
+===============================================================
+
+.. module:: sphinx.ext.doctest
+ :synopsis: Test snippets in the documentation.
Added: doctools/trunk/doc/ext/ifconfig.rst
==============================================================================
--- (empty file)
+++ doctools/trunk/doc/ext/ifconfig.rst Wed Mar 12 22:37:22 2008
@@ -0,0 +1,21 @@
+.. highlight:: rest
+
+:mod:`sphinx.ext.ifconfig` -- Include content based on configuration
+====================================================================
+
+.. module:: sphinx.ext.ifconfig
+ :synopsis: Include documentation content based on configuration values.
+
+This extension is quite simple, and features only one directive:
+
+.. directive:: ifconfig
+
+ Include content of the directive only if the Python expression given as an
+ argument is ``True``, evaluated in the namespace of the project's
+ configuration (that is, all variables from :file:`conf.py` are available).
+
+ For example, one could write ::
+
+ .. ifconfig:: releaselevel in ('alpha', 'beta', 'rc')
+
+ This stuff is only included in the built docs for unstable versions.
Added: doctools/trunk/doc/ext/refcounting.rst
==============================================================================
--- (empty file)
+++ doctools/trunk/doc/ext/refcounting.rst Wed Mar 12 22:37:22 2008
@@ -0,0 +1,5 @@
+:mod:`sphinx.ext.refcounting` -- Keep track of reference counting behavior
+==========================================================================
+
+.. module:: sphinx.ext.refcounting
+ :synopsis: Keep track of reference counting behavior.
Modified: doctools/trunk/doc/extensions.rst
==============================================================================
--- doctools/trunk/doc/extensions.rst (original)
+++ doctools/trunk/doc/extensions.rst Wed Mar 12 22:37:22 2008
@@ -15,96 +15,21 @@
are so-called "hook points" at strategic places throughout the build process,
where an extension can register a hook and run specialized code.
-Each Sphinx extension is a Python module with at least a :func:`setup` function.
-This function is called at initialization time with one argument, the
-application object representing the Sphinx process. This application object has
-the following public API:
+.. toctree::
-.. method:: Application.add_builder(builder)
+ ext/api.rst
- Register a new builder. *builder* must be a class that inherits from
- :class:`~sphinx.builder.Builder`.
-.. method:: Application.add_config_value(name, default, rebuild_env)
+Builtin Sphinx extensions
+-------------------------
- Register a configuration value. This is necessary for Sphinx to recognize
- new values and set default values accordingly. The *name* should be prefixed
- with the extension name, to avoid clashes. The *default* value can be any
- Python object. The boolean value *rebuild_env* must be ``True`` if a change
- in the setting only takes effect when a document is parsed -- this means that
- the whole environment must be rebuilt.
+These extensions are built in and can be activated by respective entries in the
+:confval:`extensions` configuration value:
-.. method:: Application.add_event(name)
+.. toctree::
- Register an event called *name*.
-
-.. method:: Application.add_node(node)
-
- Register a Docutils node class. This is necessary for Docutils internals.
- It may also be used in the future to validate nodes in the parsed documents.
-
-.. method:: Application.add_directive(name, cls, content, arguments, **options)
-
- Register a Docutils directive. *name* must be the prospective directive
- name, *func* the directive function (see the Docutils documentation - XXX
- ref) for details about the signature and return value. *content*,
- *arguments* and *options* are set as attributes on the function and determine
- whether the directive has content, arguments and options, respectively. For
- their exact meaning, please consult the Docutils documentation.
-
-.. method:: Application.add_role(name, role)
-
- Register a Docutils role. *name* must be the role name that occurs in the
- source, *role* the role function (see the Docutils documentation on details).
-
-.. method:: Application.add_description_unit(directivename, rolename, indexdesc='', parse_node=None)
-
- XXX
-
-.. method:: Application.connect(event, callback)
-
- Register *callback* to be called when *event* is emitted. For details on
- available core events and the arguments of callback functions, please see
- :ref:`events`.
-
- The method returns a "listener ID" that can be used as an argument to
- :meth:`disconnect`.
-
-.. method:: Application.disconnect(listener_id)
-
- Unregister callback *listener_id*.
-
-.. method:: Application.emit(event, *arguments)
-
- Emit *event* and pass *arguments* to the callback functions. Do not emit
- core Sphinx events in extensions!
-
-
-.. exception:: ExtensionError
-
- All these functions raise this exception if something went wrong with the
- extension API.
-
-Examples of using the Sphinx extension API can be seen in the :mod:`sphinx.ext`
-package.
-
-
-.. _events:
-
-Sphinx core events
-------------------
-
-These events are known to the core:
-
-====================== =================================== =========
-Event name Emitted when Arguments
-====================== =================================== =========
-``'builder-inited'`` the builder object has been created -none-
-``'doctree-read'`` a doctree has been parsed and read *doctree*
- by the environment, and is about to
- be pickled
-``'doctree-resolved'`` a doctree has been "resolved" by *doctree*, *docname*
- the environment, that is, all
- references and TOCs have been
- inserted
-====================== =================================== =========
+ ext/autodoc.rst
+ ext/doctest.rst
+ ext/refcounting.rst
+ ext/ifconfig.rst
+ ext/coverage.rst
Modified: doctools/trunk/doc/intro.rst
==============================================================================
--- doctools/trunk/doc/intro.rst (original)
+++ doctools/trunk/doc/intro.rst Wed Mar 12 22:37:22 2008
@@ -1,11 +1,90 @@
Introduction
============
+This is the documentation for the Sphinx documentation builder. Sphinx is a
+tool that translates a set of reStructuredText_ source files into various output
+formats, automatically producing cross-references, indices etc.
+.. XXX web app
Prerequisites
-------------
+Sphinx needs at least **Python 2.4** to run. If you like to have source code
+highlighting support, you must also install the Pygments_ library, which you can
+do via setuptools' easy_install.
+
+.. _reStructuredText: http://docutils.sf.net/rst.html
+.. _Pygments: http://pygments.org
+
+
+Setting up a documentation root
+-------------------------------
+
+The root directory of a documentation collection is called the
+:dfn:`documentation root`. There's nothing special about it; it just needs to
+contain the Sphinx configuration file, :file:`conf.py`.
+
+Sphinx comes with a script called :program:`sphinx-quickstart.py` that sets up a
+documentation root and creates a default :file:`conf.py` from a few questions
+it asks you. Just run ::
+
+ $ sphinx-quickstart.py
+
+and answer the questions.
+
+.. XXX environment
+
Running a build
---------------
+
+A build is started with the :program:`sphinx-build.py` script. It is called
+like this::
+
+ $ sphinx-build.py -b latex sourcedir builddir
+
+where *sourcedir* is the :term:`documentation root`, and *builddir* is the
+directory in which you want to place the built documentation (it must be an
+existing directory). The :option:`-b` option selects a builder; in this example
+Sphinx will build LaTeX files.
+
+The :program:`sphinx-build.py` script has several more options:
+
+**-a**
+ If given, always write all output files. The default is to only write output
+ files for new and changed source files. (This may not apply to all
+ builders.)
+
+**-E**
+ Don't use a saved :term:`environment` (the structure caching all
+ cross-references), but rebuild it completely. The default is to only read
+ and parse source files that are new or have changed since the last run.
+
+**-d** *path*
+ Since Sphinx has to read and parse all source files before it can write an
+ output file, the parsed source files are cached as "doctree pickles".
+ Normally, these files are put in a directory called :file:`.doctrees` under
+ the build directory; with this option you can select a different cache
+ directory (the doctrees can be shared between all builders).
+
+**-D** *setting=value*
+ Override a configuration value set in the :file:`conf.py` file. (The value
+ must be a string value.)
+
+**-N**
+ Do not do colored output. (On Windows, colored output is disabled in any
+ case.)
+
+**-q**
+ Do not output anything on standard output, only write warnings to standard
+ error.
+
+**-P**
+ (Useful for debugging only.) Run the Python debugger, :mod:`pdb`, if an
+ unhandled exception occurs while building.
+
+
+You can also give one or more filenames on the command line after the source and
+build directories. Sphinx will then try to build only these output files (and
+their dependencies).
Modified: doctools/trunk/doc/templating.rst
==============================================================================
--- doctools/trunk/doc/templating.rst (original)
+++ doctools/trunk/doc/templating.rst Wed Mar 12 22:37:22 2008
@@ -2,3 +2,61 @@
Templating
==========
+
+Sphinx uses the `Jinja <http://jinja.pocoo.org>` templating engine for its HTML
+templates. Jinja is a text-based engine, and inspired by Django templates, so
+anyone having used Django will already be familiar with it. It also has
+excellent documentation for those who need to make themselves familiar with it.
+
+The most important concept in Jinja is :dfn:`template inheritance`, which means
+that you can overwrite only specific blocks within a template, customizing it
+while also keeping the changes at a minimum.
+
+Inheritance is done via two directives, ``extends`` and ``block``.
+
+.. template path
+ blocks
+ extends !template
+
+These are the blocks that are predefined in Sphinx' ``layout.html`` template:
+
+**doctype**
+ The doctype, by default HTML 4 Transitional.
+
+**rellinks**
+ HTML ``<link rel=`` links in the head, by default filled with various links.
+
+**extrahead**
+ Block in the ``<head>`` tag, by default empty.
+
+**beforerelbar**
+ Block before the "related bar" (the navigation links at the page top), by
+ default empty. Use this to insert a page header.
+
+**relbar**
+ The "related bar" by default. Overwrite this block to customize the entire
+ navigation bar.
+
+**rootrellink**
+ The most parent relbar link, by default pointing to the "index" document with
+ a caption of e.g. "Project v0.1 documentation".
+
+**relbaritems**
+ Block in the ``<ul>`` used for relbar items, by default empty. Use this to
+ add more items.
+
+**afterrelbar**
+ Block between relbar and document body, by default empty.
+
+**body**
+ Block in the document body. This should be overwritten by every child
+ template, e.g. :file:`page.html` puts the page content there.
+
+**beforesidebar**
+ Block between body and sidebar, by default empty.
+
+**sidebar**
+ Contains the whole sidebar.
+
+**aftersidebar**
+ Block between
More information about the Python-checkins
mailing list