[Numpy-discussion] Sphinx custom extension mess, and patches

[josef.pktd at gmail.com]

On Sun, Feb 15, 2009 at 9:04 AM, Gael Varoquaux
<gael.varoquaux at normalesup.org> wrote:
> Hi all,
>
> Sorry for the multiple posting, this concerns various groups, and I'd
> rather the information not be lost.
>
> While working on getting our in-lab library ready to be merged with NiPy,
> I ran into some sort of 'sphinx extension mess' where various sphinx
> extension would have side effects on each other, and most important, the
> extensions did not work with sphinx trunk.
>
> I got the side effects to be limited by cleaning up the generated code
> from autosummary before each run: I added the following code in my
> sphinx conf.py:
>
> ################################################################################
> # Hack: run the autosummary generation script
> import shutil
> if os.path.exists('generated'):
>    shutil.rmtree('generated')
> os.system('%s sphinxext/autosummary_generate.py -o generated *.rst' %
>            sys.executable)
> ################################################################################
>
> I am attaching a diff of all the modifications I made to get the various
> extensions to work. I hope you can use it to get your various extensions
> working on sphinx trunk quicker. For the NiPy guys, I will be committing
> these changes in the fff2 tree soon, and we can go over this at the
> sprint.
>
> This does raise a problem: this extension code is all over the place, in
> various repository. Some of the code cannot live in the sphinx repo, as
> it introduces dependencies. However, as the extensions are not importable
> from Python (I can't do 'from matplotlib.sphinxext import mathmpl'), the
> different projects using them end up copying them in their repo, and thus
> there are several versions floating around not updated. Some of the
> extensions would do not add externa dependencies to sphinx. These should
> be pushed into sphinx, with tests. That way as sphinx evolves, they do
> not break.
>
> Gaël
>


In my setup the plot directive doesn't create any graphs, it always
skips plots with the following warning

WARNING: C:\Josef\_progs\building\scipy\scipy-trunk-new-r5551\doc\source\tutoria
l\stats.rst:300: (ERROR/3) Error in "plot" directive:
no content permitted.

When debugging this, I discovered that in plot_directive.py it creates
the `class plot_directive(Directive)`
which doesn't seem to work. If I use the same function as in the other
path of the try except, then graphs are
correctly created. I don't know if this is specific to my version
combination or if this is a bug.
>>> import docutils
>>> docutils.__version__
'0.5'
>>> import sphinx
>>> sphinx.__version__
'0.5'
>>>

Josef

-------------------------------- plot_directive.py  starting  line 417
----------
try:
    from docutils.parsers.rst import Directive
except ImportError:
    from docutils.parsers.rst.directives import _directives

    def plot_directive(name, arguments, options, content, lineno,
                       content_offset, block_text, state, state_machine):
        return run(arguments, content, options, state_machine, state, lineno)
    plot_directive.__doc__ = __doc__
else:
    print 'running plot_directive class'
    #this class doesn't do anything
##    class plot_directive(Directive):
##        def run(self):
##            return run(self.arguments, self.content, self.options,
##                       self.state_machine, self.state, self.lineno)
    #copied from above
    def plot_directive(name, arguments, options, content, lineno,
                       content_offset, block_text, state, state_machine):
        return run(arguments, content, options, state_machine, state, lineno)

    plot_directive.__doc__ = __doc__