[Python-checkins] r61534 - in doctools/trunk/doc: config.rst ext/appapi.rst glossary.rst markup/inline.rst

[georg.brandl]

Author: georg.brandl
Date: Tue Mar 18 19:19:21 2008
New Revision: 61534

Modified:
   doctools/trunk/doc/config.rst
   doctools/trunk/doc/ext/appapi.rst
   doctools/trunk/doc/glossary.rst
   doctools/trunk/doc/markup/inline.rst
Log:
Fill in some XXXs.


Modified: doctools/trunk/doc/config.rst
==============================================================================
--- doctools/trunk/doc/config.rst	(original)
+++ doctools/trunk/doc/config.rst	Tue Mar 18 19:19:21 2008
@@ -194,10 +194,21 @@
 
 .. confval:: latex_documents
 
-   Grouping the document tree into LaTeX files. List of tuples (source start
-   file, target name, title, author, document class [howto/manual]).
-
-   XXX expand.
+   This value determines how to group the document tree into LaTeX source files.
+   It must be a list of tuples ``(startdocname, targetname, title, author,
+   documentclass)``, where the items are:
+
+   * *startdocname*: document name that is the "root" of the LaTeX file.  All
+     documents referenced by it in TOC trees will be included in the LaTeX file
+     too.  (If you want only one LaTeX file, use your :confval:`master_doc`
+     here.)
+   * *targetname*: file name of the LaTeX file in the output directory.
+   * *title*: LaTeX document title.  Can be empty to use the title of the
+     *startdoc*.
+   * *author*: Author for the LaTeX document.
+   * *documentclass*: Must be one of ``'manual'`` or ``'howto'``.  Only "manual"
+     documents will get appendices.  Also, howtos will have a simpler title
+     page.
 
 .. confval:: latex_appendices
 

Modified: doctools/trunk/doc/ext/appapi.rst
==============================================================================
--- doctools/trunk/doc/ext/appapi.rst	(original)
+++ doctools/trunk/doc/ext/appapi.rst	Tue Mar 18 19:19:21 2008
@@ -1,3 +1,5 @@
+.. highlight:: rest
+
 Extension API
 =============
 
@@ -32,20 +34,50 @@
 .. 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.
+   name, *func* the directive function 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.
+
+   .. XXX once we target docutils 0.5, update this
    
 .. 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).
+   source, *role* the role function (see the `Docutils documentation
+   <http://docutils.sourceforge.net/docs/howto/rst-roles.html>`_ on details).
 
 .. method:: Application.add_description_unit(directivename, rolename, indexdesc='', parse_node=None)
 
-   XXX
+   This method is a very convenient way to add a new type of information that
+   can be cross-referenced.  It will do this:
+
+   * Create a new directive (called *directivename*) for a :term:`description
+     unit`.  It will automatically add index entries if *indexdesc* is nonempty.
+   * Create a new role (called *rolename*) to cross-reference to these
+     description units.
+   * If you provide *parse_node*, it must be a function that takes a string and
+     a docutils node, and it must populate the node with children parsed from
+     the string.  See the :file:`ext.py` file in the source for this
+     documentation for details.
+
+   For example, if you have this call in a custom Sphinx extension::
+
+      app.add_description_unit('directive', 'dir', 'directive')
+
+   you can use this markup in your documents::
+
+      .. directive:: function
+
+         Document a function.
+
+      <...>
+
+      See also the :dir:`function` directive.
+
+   For the role content, you have the same options as for standard Sphinx roles
+   (see :ref:`xref-syntax`).
 
 .. method:: Application.connect(event, callback)
 

Modified: doctools/trunk/doc/glossary.rst
==============================================================================
--- doctools/trunk/doc/glossary.rst	(original)
+++ doctools/trunk/doc/glossary.rst	Tue Mar 18 19:19:21 2008
@@ -15,7 +15,9 @@
       See :ref:`builders` for an overview over Sphinx' built-in builders.
 
    description unit
-      XXX
+      The basic building block of Sphinx documentation.  Every "description
+      directive" (e.g. :dir:`function` or :dir:`describe`) creates such a unit;
+      and most units can be cross-referenced to.
 
    documentation root
       The directory which contains the documentation's :file:`conf.py` file and

Modified: doctools/trunk/doc/markup/inline.rst
==============================================================================
--- doctools/trunk/doc/markup/inline.rst	(original)
+++ doctools/trunk/doc/markup/inline.rst	Tue Mar 18 19:19:21 2008
@@ -15,6 +15,8 @@
    free to use it for anything you like. 
 
 
+.. _xref-syntax:
+
 Cross-referencing syntax
 ------------------------