Menu
▾
▴
matplotlib-devel
|
From: Gael V. <gae...@no...> - 2009-02-15 14:04:14
Attachments:
sphinxext.diff
|
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
|
|
From: Michael D. <md...@st...> - 2009-02-16 13:54:44
|
Gael,
You raise a very good point about the duplication of code around. As a
case in point, the patches you provided no longer apply to the
"canonical" (or at least original) versions of the plugins that began
life in matplotlib. Recent versions of Sphinx have a proper extension
API, so that "try ... except" importing is no longer necessary.
For mathmpl.py --- I will move that into the matplotlib installed code
tree, so, as you suggest, "from matplotlib.sphinxext import mathmpl"
will work. Obviously, that won't really provide traction until the next
release of matplotlib. And it relies on only_directive.py, so I will
probably have to put that in matplotlib as well for now, though that is
a reasonable candidate for inclusion in Sphinx.
I have submitted inheritance_diagram.py to Sphinx already. There didn't
seem to be much interest, and there were some details (particularly how
it deals with files), that weren't "the Sphinx way", and there few
documents and/or examples etc. at the time about how to do it right.
Someone else ended up re-engineering it to use pygraphviz which felt
pretty heavy weight to me. So the thing kind of stalled. But it's
probably worth another push.
Mike
Gael Varoquaux 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
>
> ------------------------------------------------------------------------
>
> ------------------------------------------------------------------------------
> Open Source Business Conference (OSBC), March 24-25, 2009, San Francisco, CA
> -OSBC tackles the biggest issue in open source: Open Sourcing the Enterprise
> -Strategies to boost innovation and cut costs with open source participation
> -Receive a $600 discount off the registration fee with the source code: SFAD
> http://p.sf.net/sfu/XcvMzF8H
> ------------------------------------------------------------------------
>
> _______________________________________________
> Matplotlib-devel mailing list
> Mat...@li...
> https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
--
Michael Droettboom
Science Software Branch
Operations and Engineering Division
Space Telescope Science Institute
Operated by AURA for NASA
|
|
From: Georg B. <ge...@py...> - 2009-02-16 23:53:25
|
Michael Droettboom schrieb: > Gael, > > You raise a very good point about the duplication of code around. As a > case in point, the patches you provided no longer apply to the > "canonical" (or at least original) versions of the plugins that began > life in matplotlib. Recent versions of Sphinx have a proper extension > API, so that "try ... except" importing is no longer necessary. > > For mathmpl.py --- I will move that into the matplotlib installed code > tree, so, as you suggest, "from matplotlib.sphinxext import mathmpl" > will work. Obviously, that won't really provide traction until the next > release of matplotlib. And it relies on only_directive.py, so I will > probably have to put that in matplotlib as well for now, though that is > a reasonable candidate for inclusion in Sphinx. The "only" is so trivial that it will, in this or a more extended form, certainly be part of 0.6, which will not come out later than Feb 31 ;) > I have submitted inheritance_diagram.py to Sphinx already. There didn't > seem to be much interest, and there were some details (particularly how > it deals with files), that weren't "the Sphinx way", and there few > documents and/or examples etc. at the time about how to do it right. > Someone else ended up re-engineering it to use pygraphviz which felt > pretty heavy weight to me. So the thing kind of stalled. But it's > probably worth another push. The mails are still in my "look at it again" folder. I kind of agree that using pygraphviz is counterproductive, since many systems have graphviz but no so many, I suspect, pygraphviz. Is the current version of the inheritance_diagram.py the one in matplotlib? cheers, Georg |
|
From: Robert K. <rob...@gm...> - 2009-02-16 19:36:13
|
On Sun, Feb 15, 2009 at 08:04, Gael Varoquaux <gae...@no...> 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. At one point, some of us had a plan to keep all of these "scientific" extensions collected here: http://sphinx.googlecode.com/svn/contrib/trunk/numpyext/ SVN-using projects could use svn:externals to include these in their projects without diverging the code. I really don't know why this plan changed. Pauli? -- Robert Kern "I have come to believe that the whole world is an enigma, a harmless enigma that is made terrible by our own mad attempt to interpret it as though it had an underlying truth." -- Umberto Eco |
|
From: Pauli V. <pa...@ik...> - 2009-02-16 20:20:17
|
Mon, 16 Feb 2009 13:36:07 -0600, Robert Kern wrote: [clip] > At one point, some of us had a plan to keep all of these "scientific" > extensions collected here: > > http://sphinx.googlecode.com/svn/contrib/trunk/numpyext/ > > SVN-using projects could use svn:externals to include these in their > projects without diverging the code. I really don't know why this plan > changed. Pauli? I think my reasons for moving the extensions to Scipy SVN was mainly that (i) it seemed clearer to keep the code where it was mainly used, also for bug tracking and mailing list purposes, (ii) Sphinx's google-code SVN seemed quite dead and obscure, and was difficult to find, (iii) svn:externals would work also against Numpy's repository. A better thing to do might have been to rally people to put also their extensions there and press for better advertisement. We can of course still do this and revive the idea; it would be good to get a slightly bigger starting mass, though. -- Pauli Virtanen |
|
From: Georg B. <ge...@py...> - 2009-02-16 23:51:18
|
Gael Varoquaux schrieb:
> 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.
Which is of course kind of my fault, because I keep changing the API :)
But it must also be said that during 0.x, I tend to view cleanliness and
good code as more important than 100% backwards compatibility.
> 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.
I'm all for it. In the case of autosummary, I'm guilty of not getting it
in sooner. This will change soon. In other cases, I don't even know of
the extension, probably because those who write it deem it as too
project-specific to contribute it.
I don't ask for too much if an extension is contributed, so by all means
do at least post about your extensions!
Georg
|
|
From: Gael V. <gae...@no...> - 2009-02-16 23:21:23
|
On Tue, Feb 17, 2009 at 12:17:17AM +0100, Georg Brandl wrote: > I'm all for it. In the case of autosummary, I'm guilty of not getting it > in sooner. This will change soon. In other cases, I don't even know of > the extension, probably because those who write it deem it as too > project-specific to contribute it. > I don't ask for too much if an extension is contributed, so by all means > do at least post about your extensions! I am not blaming anyone, just pointing out a non ideal situation. It has already improved a lot with the matplotlib guys and the scipy guys merging some changes in extensions and publishing the extensions in an importable part of their source tree. It is true that I'll be happier when I will be able to import the only_directive, and the auto_summary from sphinx :). Thanks for your great work, Gaël |
|
From: Fernando P. <fpe...@gm...> - 2009-02-21 01:02:51
|
On Mon, Feb 16, 2009 at 3:21 PM, Gael Varoquaux <gae...@no...> wrote: > I am not blaming anyone, just pointing out a non ideal situation. It has > already improved a lot with the matplotlib guys and the scipy guys > merging some changes in extensions and publishing the extensions in an > importable part of their source tree. In keeping with the spirit of trying to get all of these extension changes upstream so that we can all eventually stop carrying our own copies, below is a tiny change I just made to the inheritance diagram one. This is needed to ensure that the figure is separated from any surrounding text, since otherwise you get hideous off-screen diagrams in the rendered PDF. This has been committed to the nipy trunk already. Similarly (for the pymvpa crowd), the api autogen code is now a module, and it also contains a few small fixes, in particular regarding chapter titles. Feel free to grab and update your copy: http://bazaar.launchpad.net/~nipy-developers/nipy/trunk/annotate/head%3A/tools/apigen.py I've been told the gods of numpy/sphinx don't like auto-generated docs, but I think there's a valid use case for these tools, so hopefully in the future it will be possible to include them upstream for us lesser mortals to use. If not, I guess we'll just continue to carry our copies around :) Cheers, f # diff, inline because it's so trivial: === modified file 'doc/sphinxext/inheritance_diagram.py' --- doc/sphinxext/inheritance_diagram.py 2009-01-30 02:00:57 +0000 +++ doc/sphinxext/inheritance_diagram.py 2009-02-20 21:11:38 +0000 @@ -370,7 +370,7 @@ graph.run_dot(['-Tpdf', '-o%s' % pdf_path], name, parts, graph_options={'size': '"6.0,6.0"'}) - return '\\includegraphics{%s}' % pdf_path + return '\n\\includegraphics{%s}\n\n' % pdf_path def visit_inheritance_diagram(inner_func): """ |
|
From: Michael D. <md...@st...> - 2009-02-23 15:00:11
|
Thanks, Fernando. I've applied your patch to matplotlib (branch and trunk). Mike Fernando Perez wrote: > On Mon, Feb 16, 2009 at 3:21 PM, Gael Varoquaux > <gae...@no...> wrote: > > >> I am not blaming anyone, just pointing out a non ideal situation. It has >> already improved a lot with the matplotlib guys and the scipy guys >> merging some changes in extensions and publishing the extensions in an >> importable part of their source tree. >> > > In keeping with the spirit of trying to get all of these extension > changes upstream so that we can all eventually stop carrying our own > copies, below is a tiny change I just made to the inheritance diagram > one. This is needed to ensure that the figure is separated from any > surrounding text, since otherwise you get hideous off-screen diagrams > in the rendered PDF. > > This has been committed to the nipy trunk already. > > Similarly (for the pymvpa crowd), the api autogen code is now a > module, and it also contains a few small fixes, in particular > regarding chapter titles. Feel free to grab and update your copy: > > http://bazaar.launchpad.net/~nipy-developers/nipy/trunk/annotate/head%3A/tools/apigen.py > > I've been told the gods of numpy/sphinx don't like auto-generated > docs, but I think there's a valid use case for these tools, so > hopefully in the future it will be possible to include them upstream > for us lesser mortals to use. If not, I guess we'll just continue to > carry our copies around :) > > Cheers, > > f > > # diff, inline because it's so trivial: > > === modified file 'doc/sphinxext/inheritance_diagram.py' > --- doc/sphinxext/inheritance_diagram.py 2009-01-30 02:00:57 +0000 > +++ doc/sphinxext/inheritance_diagram.py 2009-02-20 21:11:38 +0000 > @@ -370,7 +370,7 @@ > > graph.run_dot(['-Tpdf', '-o%s' % pdf_path], > name, parts, graph_options={'size': '"6.0,6.0"'}) > - return '\\includegraphics{%s}' % pdf_path > + return '\n\\includegraphics{%s}\n\n' % pdf_path > > def visit_inheritance_diagram(inner_func): > """ > > ------------------------------------------------------------------------------ > Open Source Business Conference (OSBC), March 24-25, 2009, San Francisco, CA > -OSBC tackles the biggest issue in open source: Open Sourcing the Enterprise > -Strategies to boost innovation and cut costs with open source participation > -Receive a $600 discount off the registration fee with the source code: SFAD > http://p.sf.net/sfu/XcvMzF8H > _______________________________________________ > Matplotlib-devel mailing list > Mat...@li... > https://lists.sourceforge.net/lists/listinfo/matplotlib-devel > -- Michael Droettboom Science Software Branch Operations and Engineering Division Space Telescope Science Institute Operated by AURA for NASA |
×
Want the latest updates on software, tech news, and AI?
Get latest updates about software, tech news, and AI from SourceForge directly in your inbox once a month.
Thanks for helping keep SourceForge clean.
X