Re: [matplotlib-devel] future of mpl documentation

[Darren D. <dar...@co...>]

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.

We can potentially pare back the size of the api reference, since we have some 
control over what is and is not included.

Darren