Anonymous committed 00ba093

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

  • Participants
  • Parent commits 0461ad7

Comments (0)

Files changed (3)

   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.

File doc/markup/desc.rst

 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
    .. moduleauthor:: Eric Cleese <eric@python.invalid>
    .. moduleauthor:: John Idle <john@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.
    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

File sphinx/

 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