Re: [matplotlib-devel] future of mpl documentation

[John H. <jd...@gm...>]

On Fri, May 23, 2008 at 3:00 PM, Darren Dale <dar...@co...> wrote:
> On Friday 23 May 2008 03:02:55 pm John Hunter wrote:
>> On Fri, May 23, 2008 at 9:54 AM, John Hunter <jd...@gm...> wrote:
>> > It certainly would make the docs more useful to be able to link to the
>> > class and function references.  Argg.  I guess I'll just have to give
>> > up my desire to have clean ASCII here, since most people are going to
>> > read this on the web or as PDF so we should target that.  One
>> > question: suppose we use class:`Line2D` and include the reference docs
>> > in a single build, eg for the web site and a master PDF, but we want
>> > to provide on some occasions a lighter PDF, eg just a few of the docs
>> > w/o the reference.  Will sphinx be somewhat smart and just format the
>> > class:`Line2D` as monospace when it cannot find the references?
>>
>> I've been experimenting with including the api docs in the same build
>> to see if I could get linking to work, eg links in the pyplot tutorial
>> to matplotlib.lines.Line2D.  I know if we go this route some more
>> reorganization will be needed, so we should figure that out and get
>> our commits in and then freeze while Darren does the reorg.
>
> I was able to get the linking to work, as I posted in my last message, but
> forgot to address a reorg. I'm happy to do it, but I will be out of town and
> away from a computer Saturday morning through Monday afternoon. If we decide
> to include the api in the users guide (I think it is worth considering), I
> can do it when I get back.

OK, sounds good.

I tried including the pyplot reference docs but it is croaking on the
docstrings there.  I suppose  some of them have some invalid rest.
Unfortunately the line numbers don't make a lot of sense

   updating environment: 17 added, 0 changed, 0 removed
    reading... add_new_projection api api_artists api_introduction
api_pyplot reST markup error:
    /home/titan/johnh/python/svn/matplotlib.trunk/matplotlib/doc/users_guide/api_pyplot.txt:1127:
(SEVERE/4) Unexpected section title or transition.

    ****************


since api_pyplt.txt is just a small file which does:

    *****************
    matplotlib.pyplot
    *****************

    :mod:`matplotlib.pyplot`
    =============================

    .. automodule:: matplotlib.pyplot
    :members:
    :undoc-members:

Have you had any success in figuring out how to know what is causing
these kinds of errors, ie where to go in the module docs to fix them?

JDH