matplotlib-devel Mailing List for matplotlib

On Mon, May 16, 2011 at 5:28 PM, Benjamin Root <ben...@ou...> wrote:
> On Monday, May 16, 2011, John Hunter <jd...@gm...> wrote:
> >
> >
> > On Mon, May 16, 2011 at 2:52 PM, Eric Firing <ef...@ha...> wrote:
> >
> >
> >
> > I had no idea this would open such a big can of worms! The strategy
> > question here is, what do we want to include in the html API docs?
> >
> > It looks like the process of setting up the sphinx API docs was never
> > completed; the present set of modules that are included ranges from the
> > fundamental (e.g. figure.py) to the peripheral (e.g. afm.py), but I
> > doubt that text.py, for example, was deliberately excluded.
> >
> > I don't see any major disadvantage to including all modules. It might
> > make sense to present them in categories, though, instead of dumping
> > them all into a single alphabetical list.
> >
> > Perhaps Mike and John will have sage advice.
> >
> >
> > Not all of the doc strings have been converted to rest. Back when I was
> actively working on the docs, I would add a module to the API table of
> contents when I had at least done a first pass at converting the docs to
> rest. This isn't a requirement, but it helps explain why some modules and
> not others are in the list.
> >
>
> Well, I will take a look at what is currently converted and see if any
> of those can get added.
>
> Ben Root
>
Ok, on my pull request, I have made a number of commits. In particular, I
have ReST-ified widgets.py (although there are still some more things to do
in it). I have added a widgets api file to the api docs, and also renamed
the headers for each api file so that the "matplotlib" part didn't show up
repeatedly in the ToC.
There are still plenty of odds and ends that can be done. I want to clean
up the examples page so that the "matplotlib: " string doesn't show up for
every entry as well. Furthermore, the widgets module has some docstrings
that seems like the author got distracted halfway through writing it and
never came back. I marked those docstrings with FIXME comments.
Let me know what you all think!
Ben Root

On Thu, May 19, 2011 at 1:42 PM, John Hunter <jd...@gm...> wrote:
>
>
> On Thu, May 19, 2011 at 1:16 PM, Benjamin Root <ben...@ou...> wrote:
>
>> I have come across a slight oddity while working on the docs today. I
>> wanted to make some small changes to the ReST docs for the examples section,
>> but then I noticed that my docs/examples directory had the new animation
>> examples and a directory for "old_animations". Figuring that this could not
>> be correct, I checked on github, and for branch v1.0.x, there is no
>> "docs/examples" directory. Is this directory created and its contents
>> filled whenever I run setup.py? The modification time for the folder seems
>> to indicate that.
>>
>
> This is created and built by the doc builder, so it is when you run make.py
> from the doc dir, not when you run setup.py from the src dir.
>
> Check doc/sphinxext/gen_rst.py and doc/sphinxext/gen_gallery.py
>
> If you run
>
>
> > python make.py clean
>
> from the doc dir, it should clean it up.
>
> JDH
>
Ah, that makes sense, although the mod time for my directory doesn't...
maybe the setup.py is somehow touching that directory?
Anyway, when I cleaned up the docs with the above command, it removed
doc/pyplots/tex_demo.png, which appears to have been under version control.
I guess this is a mistake in either the version control, or the cleanup
script (which left behind other png files in the same directory).
Ben Root

On Thu, May 19, 2011 at 1:16 PM, Benjamin Root <ben...@ou...> wrote:
> I have come across a slight oddity while working on the docs today. I
> wanted to make some small changes to the ReST docs for the examples section,
> but then I noticed that my docs/examples directory had the new animation
> examples and a directory for "old_animations". Figuring that this could not
> be correct, I checked on github, and for branch v1.0.x, there is no
> "docs/examples" directory. Is this directory created and its contents
> filled whenever I run setup.py? The modification time for the folder seems
> to indicate that.
>
This is created and built by the doc builder, so it is when you run make.py
from the doc dir, not when you run setup.py from the src dir.
Check doc/sphinxext/gen_rst.py and doc/sphinxext/gen_gallery.py
If you run
 > python make.py clean
from the doc dir, it should clean it up.
JDH

I have come across a slight oddity while working on the docs today. I
wanted to make some small changes to the ReST docs for the examples section,
but then I noticed that my docs/examples directory had the new animation
examples and a directory for "old_animations". Figuring that this could not
be correct, I checked on github, and for branch v1.0.x, there is no
"docs/examples" directory. Is this directory created and its contents
filled whenever I run setup.py? The modification time for the folder seems
to indicate that.
Thanks,
Ben Root