[Python-checkins] r62326 - in doctools/trunk: CHANGES doc/markup/desc.rst sphinx/directives.py

[georg.brandl]

Author: georg.brandl
Date: Sun Apr 13 19:57:14 2008
New Revision: 62326

Log:
Support ``currentmodule`` directive, for docs that spread documentation
for a module's contents over multiple files.


Modified:
   doctools/trunk/CHANGES
   doctools/trunk/doc/markup/desc.rst
   doctools/trunk/sphinx/directives.py

Modified: doctools/trunk/CHANGES
==============================================================================
--- doctools/trunk/CHANGES	(original)
+++ doctools/trunk/CHANGES	Sun Apr 13 19:57:14 2008
@@ -9,6 +9,10 @@
   It takes a standard docutils ``Transform`` subclass which is then
   applied by Sphinx' reader on parsing reST document trees.
 
+* sphinx.directives: New directive, ``currentmodule``.  It can be used
+  to indicate the module name of the following documented things without
+  creating index entries.
+
 * sphinx.ext.autodoc: Don't check ``__module__`` for explicitly given
   members.  Remove "self" in class constructor argument list.
 

Modified: doctools/trunk/doc/markup/desc.rst
==============================================================================
--- doctools/trunk/doc/markup/desc.rst	(original)
+++ doctools/trunk/doc/markup/desc.rst	Sun Apr 13 19:57:14 2008
@@ -4,9 +4,8 @@
 ----------------------
 
 The markup described in this section is used to provide information about a
-module being documented.  Each module should be documented in its own file.
-Normally this markup appears after the title heading of that file; a typical
-file might start like this::
+module being documented.  Normally this markup appears after a title heading; a
+typical module section might start like this::
 
    :mod:`parrot` -- Dead parrot access
    ===================================
@@ -17,14 +16,14 @@
    .. moduleauthor:: Eric Cleese <eric at python.invalid>
    .. moduleauthor:: John Idle <john at python.invalid>
 
-As you can see, the module-specific markup consists of two directives, the
-``module`` directive and the ``moduleauthor`` directive.
+
+The directives you can use for module are:
 
 .. directive:: .. module:: name
 
    This directive marks the beginning of the description of a module (or package
    submodule, in which case the name should be fully qualified, including the
-   package name).
+   package name).  It does not create content (like e.g. :dir:`class` does).
 
    This directive will also cause an entry in the global module index.
 
@@ -41,6 +40,16 @@
    deprecated; it will be designated as such in various locations then.
 
 
+.. directive:: .. currentmodule:: name
+
+   This directive tells Sphinx that the classes, functions etc. documented from
+   here are in the given module (like :dir:`module`), but it will not create
+   index entries, an entry in the Global Module Index, or a link target for
+   :role:`mod`.  This is helpful in situations where documentation for things in
+   a module is spread over multiple files or sections -- one location has the
+   :dir:`module` directive, the others only :dir:`currentmodule`.
+
+
 .. directive:: .. moduleauthor:: name <email>
 
    The ``moduleauthor`` directive, which can appear multiple times, names the

Modified: doctools/trunk/sphinx/directives.py
==============================================================================
--- doctools/trunk/sphinx/directives.py	(original)
+++ doctools/trunk/sphinx/directives.py	Sun Apr 13 19:57:14 2008
@@ -599,6 +599,19 @@
 directives.register_directive('module', module_directive)
 
 
+def currentmodule_directive(name, arguments, options, content, lineno,
+                            content_offset, block_text, state, state_machine):
+    # This directive is just to tell people that we're documenting
+    # stuff in module foo, but links to module foo won't lead here.
+    env = state.document.settings.env
+    modname = arguments[0].strip()
+    env.currmodule = modname
+    return []
+
+currentmodule_directive.arguments = (1, 0, 0)
+directives.register_directive('currentmodule', currentmodule_directive)
+
+
 def author_directive(name, arguments, options, content, lineno,
                      content_offset, block_text, state, state_machine):
     # Show authors only if the show_authors option is on