addplied Fernando's sphinxext patch

jdh2358 · jdh2358 · commit 8c4b297a5311 · 2009-02-02T12:42:08.000Z
svn path=/trunk/matplotlib/; revision=6863
diff --git a/doc/sphinxext/inheritance_diagram.py b/doc/sphinxext/inheritance_diagram.py
@@ -42,6 +42,17 @@ class E(B): pass
 from docutils.parsers.rst import directives
 from sphinx.roles import xfileref_role
 
+def my_import(name):
+    """Module importer - taken from the python documentation.
+
+    This function allows importing names with dots in them."""
+    
+    mod = __import__(name)
+    components = name.split('.')
+    for comp in components[1:]:
+        mod = getattr(mod, comp)
+    return mod
+
 class DotException(Exception):
     pass
 
@@ -84,6 +95,13 @@ def _import_class_or_module(self, name):
             path = base
         try:
             module = __import__(path, None, None, [])
+            # We must do an import of the fully qualified name.  Otherwise if a
+            # subpackage 'a.b' is requested where 'import a' does NOT provide
+            # 'a.b' automatically, then 'a.b' will not be found below.  This
+            # second call will force the equivalent of 'import a.b' to happen
+            # after the top-level import above.
+            my_import(fullname)
+            
         except ImportError:
             raise ValueError(
                 "Could not import class or module '%s' specified for inheritance diagram" % name)
diff --git a/doc/sphinxext/ipython_console_highlighting.py b/doc/sphinxext/ipython_console_highlighting.py
@@ -1,18 +1,32 @@
+"""reST directive for syntax-highlighting ipython interactive sessions.
+"""
+
+#-----------------------------------------------------------------------------
+# Needed modules
+
+# Standard library
+import re
+
+# Third party
 from pygments.lexer import Lexer, do_insertions
-from pygments.lexers.agile import PythonConsoleLexer, PythonLexer, \
-    PythonTracebackLexer
+from pygments.lexers.agile import (PythonConsoleLexer, PythonLexer, 
+                                   PythonTracebackLexer)
 from pygments.token import Comment, Generic
+
 from sphinx import highlighting
-import re
 
+
+#-----------------------------------------------------------------------------
+# Global constants
 line_re = re.compile('.*?\n')
 
+#-----------------------------------------------------------------------------
+# Code begins - classes and functions
+
 class IPythonConsoleLexer(Lexer):
     """
     For IPython console output or doctests, such as:
 
-    Tracebacks are not currently supported.
-
     .. sourcecode:: ipython
 
       In [1]: a = 'foo'
@@ -24,7 +38,14 @@ class IPythonConsoleLexer(Lexer):
       foo
 
       In [4]: 1 / 0
+
+    Notes:
+
+      - Tracebacks are not currently supported.
+
+      - It assumes the default IPython prompts, not customized ones.
     """
+    
     name = 'IPython console session'
     aliases = ['ipython']
     mimetypes = ['text/x-ipython-console']
@@ -72,4 +93,6 @@ def get_tokens_unprocessed(self, text):
                                       pylexer.get_tokens_unprocessed(curcode)):
                 yield item
 
+#-----------------------------------------------------------------------------
+# Register the extension as a valid pygments lexer
 highlighting.lexers['ipython'] = IPythonConsoleLexer()
diff --git a/doc/sphinxext/mathmpl.py b/doc/sphinxext/mathmpl.py
@@ -1,3 +1,25 @@
+"""matplotlib-based directive for math rendering in reST using sphinx.
+
+To use this extension, add ``mathmpl`` to the list of extensions in
+:file:`conf.py`.
+
+Note:
+
+Current SVN versions of Sphinx now include built-in support for math.
+There are two flavors:
+
+  - pngmath: uses dvipng to render the equation
+
+  - jsmath: renders the math in the browser using Javascript
+
+To use these extensions instead of the code in this module, add
+``sphinx.ext.pngmath`` or ``sphinx.ext.jsmath`` to the list of extensions in
+:file:`conf.py` instead of ``mathmpl``.
+
+All three of these options for math are designed to behave in the same
+way.
+"""
+
 import os
 import sys
 try:
diff --git a/doc/sphinxext/only_directives.py b/doc/sphinxext/only_directives.py
@@ -1,11 +1,15 @@
-#
-# A pair of directives for inserting content that will only appear in
-# either html or latex.
-#
+"""Sphinx directives for selective inclusion of contents.
 
+A pair of directives for inserting content that will only appear in
+either html or latex.
+"""
+
+# Required modules
 from docutils.nodes import Body, Element
 from docutils.parsers.rst import directives
 
+
+# Code begins
 class only_base(Body, Element):
     def dont_traverse(self, *args, **kwargs):
         return []
