future of mpl documentation

Development matplotlib-devel
1

Yes it is nice to keep things readable for the help system.

One possibility is running the docstrings through a preprocessor as
part of the install process. This can remove extraneous reST markup,
and using tex2mail, convert latex formulae to ascii (I haven't tried
it yet, but that's what it claims to do). This also lets you plug
in attribute documentation at compile time rather than doing runtime
hacks.

However, the problem I was referring to above is that IE7 is not
rendering the xml, even for pages which did not have mathml.
This might be something simple like making sure files use .html
rather than .xml. Darren has taken the temp pages down so I can't
try that.

  - Paul

···

On Thu, May 22, 2008 at 08:45:02PM -0500, John Hunter wrote:

On Thu, May 22, 2008 at 6:08 PM, Paul Kienzle <pkienzle@...537...> wrote:

> It looks okay in Firefox 2.0.0.14 (though it did complain about missing the mathml
> fonts).
>
> IE 7 displays the xml tree.

I don't mind using latex for math where is really helps but I think we
should try to keep it to a minimum, since it appears mathml in the
browsers is poorly supported. I also want to keep the docstrings as
human readable as possible. I know that in some cases latex *adds* to
the human readability, but in other cases it detracts, so we want to
balance the elegance of the final pdflatex generated PDF output with
the reality that many will be seeing the docs either in plain text or
improperly rendered HTML. If it can be done easily enough with ascii
math art, we should prefer that.

2

I moved them when I updated mpl to split the API reference from the Users
Guide: http://dale.chess.cornell.edu/~darren/temp/matplotlib/

I just heard from Jens again, he has another extension that uses png's rather
than mathml. I'll try it when I get to work this morning, it should work in
all browsers and we can use regular html files.

Darren

···

On Friday 23 May 2008 7:08:09 am Paul Kienzle wrote:

On Thu, May 22, 2008 at 08:45:02PM -0500, John Hunter wrote:
> On Thu, May 22, 2008 at 6:08 PM, Paul Kienzle <pkienzle@...537...> wrote:
> > It looks okay in Firefox 2.0.0.14 (though it did complain about missing
> > the mathml fonts).
> >
> > IE 7 displays the xml tree.
>
> I don't mind using latex for math where is really helps but I think we
> should try to keep it to a minimum, since it appears mathml in the
> browsers is poorly supported. I also want to keep the docstrings as
> human readable as possible. I know that in some cases latex *adds* to
> the human readability, but in other cases it detracts, so we want to
> balance the elegance of the final pdflatex generated PDF output with
> the reality that many will be seeing the docs either in plain text or
> improperly rendered HTML. If it can be done easily enough with ascii
> math art, we should prefer that.

Yes it is nice to keep things readable for the help system.

One possibility is running the docstrings through a preprocessor as
part of the install process. This can remove extraneous reST markup,
and using tex2mail, convert latex formulae to ascii (I haven't tried
it yet, but that's what it claims to do). This also lets you plug
in attribute documentation at compile time rather than doing runtime
hacks.

However, the problem I was referring to above is that IE7 is not
rendering the xml, even for pages which did not have mathml.
This might be something simple like making sure files use .html
rather than .xml. Darren has taken the temp pages down so I can't
try that.

3

These examples look great, Darren.

One small detail:

The cover page of the PDFs list John and Darren as authors. I think the docs (particularly the docstrings) have probably been written by a much larger community. If it's not practical to list all contributors (probably so given all of the hands that have worked on this over the years), maybe John and Darren could be credited as editors.

Cheers,
Mike

Darren Dale wrote:

···

On Friday 23 May 2008 7:08:09 am Paul Kienzle wrote:
  

On Thu, May 22, 2008 at 08:45:02PM -0500, John Hunter wrote:
    

On Thu, May 22, 2008 at 6:08 PM, Paul Kienzle <pkienzle@...537...> wrote:
      

It looks okay in Firefox 2.0.0.14 (though it did complain about missing
the mathml fonts).

IE 7 displays the xml tree.
        

I don't mind using latex for math where is really helps but I think we
should try to keep it to a minimum, since it appears mathml in the
browsers is poorly supported. I also want to keep the docstrings as
human readable as possible. I know that in some cases latex *adds* to
the human readability, but in other cases it detracts, so we want to
balance the elegance of the final pdflatex generated PDF output with
the reality that many will be seeing the docs either in plain text or
improperly rendered HTML. If it can be done easily enough with ascii
math art, we should prefer that.
      

Yes it is nice to keep things readable for the help system.

One possibility is running the docstrings through a preprocessor as
part of the install process. This can remove extraneous reST markup,
and using tex2mail, convert latex formulae to ascii (I haven't tried
it yet, but that's what it claims to do). This also lets you plug
in attribute documentation at compile time rather than doing runtime
hacks.

However, the problem I was referring to above is that IE7 is not
rendering the xml, even for pages which did not have mathml.
This might be something simple like making sure files use .html
rather than .xml. Darren has taken the temp pages down so I can't
try that.
    
I moved them when I updated mpl to split the API reference from the Users Guide: http://dale.chess.cornell.edu/~darren/temp/matplotlib/

I just heard from Jens again, he has another extension that uses png's rather than mathml. I'll try it when I get to work this morning, it should work in all browsers and we can use regular html files.

Darren

-------------------------------------------------------------------------
This SF.net email is sponsored by: Microsoft
Defy all challenges. Microsoft(R) Visual Studio 2008.
http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/
_______________________________________________
Matplotlib-devel mailing list
Matplotlib-devel@lists.sourceforge.net
matplotlib-devel List Signup and Options
  
--
Michael Droettboom
Science Software Branch
Operations and Engineering Division
Space Telescope Science Institute
Operated by AURA for NASA

4

Hi Mike,

These examples look great, Darren.

One small detail:

The cover page of the PDFs list John and Darren as authors. I think the
docs (particularly the docstrings) have probably been written by a much
larger community. If it's not practical to list all contributors
(probably so given all of the hands that have worked on this over the
years), maybe John and Darren could be credited as editors.

Thank you for bringing this up. I was actually thinking about this on the way
to work this morning, how to give appropriate credit for everyone who has
contributed to the documentation. I'll make sure this issue is addressed.
Maybe when we get close to publishing these we can revisit the issue, it
looks like there are several people interested in contributing, and I'm sure
we all would like those efforts to receive credit.

Darren

···

On Friday 23 May 2008 08:34:35 am Michael Droettboom wrote:

5

There are a couple of minor details about formatting that might be worth working out up front before too much reST conversion begins:

How do we want to handle inline code names? For example, this passage from the Artist API tutorial:

    "The primitives represent the standard graphical objects we want to
    paint onto our canvas: Line2D, Rectangle, Text, AxesImage, etc, and
    the containers are places to put them (Axis, Axes and Figure)."

Personally, I would prefer to see all the names in monospaced type (I find it much more readable), but the additional markup may be somewhat at odds with keeping the original ReST source clean. There are also two roads to take: a) simply putting `` around them, or b) using the Sphinx cross-referencing constructs, e.g. ":class:`Line2D`".

b) is obviously a lot noisier in the original ReST, but could produce more useful online documentation. Note, however, that if we put the narrative and reference documentation in separate documents, the cross-references won't actually work between them.

Personally, I prefer whatever makes the resulting documentation products the most useful, but I know there are others that make more use of the documentation in its original form. We could preprocess some of these things out, but I would only want to go down that path if it doesn't add too much complexity.

Secondly, the ipython console sessions aren't getting syntax highlighted -- it would be nice if they did, particularly to indicate input vs. output. I'll volunteer to look into this -- I've done some pygments customization work in the past and maybe it won't be too difficult.

Cheers,
Mike

Michael Droettboom wrote:

···

These examples look great, Darren.

One small detail:

The cover page of the PDFs list John and Darren as authors. I think the docs (particularly the docstrings) have probably been written by a much larger community. If it's not practical to list all contributors (probably so given all of the hands that have worked on this over the years), maybe John and Darren could be credited as editors.

Cheers,
Mike

Darren Dale wrote:
  

On Friday 23 May 2008 7:08:09 am Paul Kienzle wrote:
  

On Thu, May 22, 2008 at 08:45:02PM -0500, John Hunter wrote:
    

On Thu, May 22, 2008 at 6:08 PM, Paul Kienzle <pkienzle@...537...> wrote:
      

It looks okay in Firefox 2.0.0.14 (though it did complain about missing
the mathml fonts).

IE 7 displays the xml tree.
        

I don't mind using latex for math where is really helps but I think we
should try to keep it to a minimum, since it appears mathml in the
browsers is poorly supported. I also want to keep the docstrings as
human readable as possible. I know that in some cases latex *adds* to
the human readability, but in other cases it detracts, so we want to
balance the elegance of the final pdflatex generated PDF output with
the reality that many will be seeing the docs either in plain text or
improperly rendered HTML. If it can be done easily enough with ascii
math art, we should prefer that.
      

Yes it is nice to keep things readable for the help system.

One possibility is running the docstrings through a preprocessor as
part of the install process. This can remove extraneous reST markup,
and using tex2mail, convert latex formulae to ascii (I haven't tried
it yet, but that's what it claims to do). This also lets you plug
in attribute documentation at compile time rather than doing runtime
hacks.

However, the problem I was referring to above is that IE7 is not
rendering the xml, even for pages which did not have mathml.
This might be something simple like making sure files use .html
rather than .xml. Darren has taken the temp pages down so I can't
try that.
    

I moved them when I updated mpl to split the API reference from the Users Guide: http://dale.chess.cornell.edu/~darren/temp/matplotlib/

I just heard from Jens again, he has another extension that uses png's rather than mathml. I'll try it when I get to work this morning, it should work in all browsers and we can use regular html files.

Darren

-------------------------------------------------------------------------
This SF.net email is sponsored by: Microsoft
Defy all challenges. Microsoft(R) Visual Studio 2008.
http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/
_______________________________________________
Matplotlib-devel mailing list
Matplotlib-devel@lists.sourceforge.net
matplotlib-devel List Signup and Options
  
--
Michael Droettboom
Science Software Branch
Operations and Engineering Division
Space Telescope Science Institute
Operated by AURA for NASA

6

I am more than happy to give credit to any and all on the
author/contributer/editor list. For now, let's have anyone who had
made a contribution and wants to be on the list just add your name,
and when we have something sizeable, Darren can organize the list
depending on how the work has been done, eg into editors, authors,
contributers as appropriate.

JDH

···

On Fri, May 23, 2008 at 7:34 AM, Michael Droettboom <mdroe@...31...> wrote:

The cover page of the PDFs list John and Darren as authors. I think the
docs (particularly the docstrings) have probably been written by a much
larger community. If it's not practical to list all contributors (probably
so given all of the hands that have worked on this over the years), maybe
John and Darren could be credited as editors.

7

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?

JDH

···

On Fri, May 23, 2008 at 8:12 AM, Michael Droettboom <mdroe@...31...> wrote:

Personally, I would prefer to see all the names in monospaced type (I find
it much more readable), but the additional markup may be somewhat at odds
with keeping the original ReST source clean. There are also two roads to
take: a) simply putting `` around them, or b) using the Sphinx
cross-referencing constructs, e.g. ":class:`Line2D`".

b) is obviously a lot noisier in the original ReST, but could produce more
useful online documentation. Note, however, that if we put the narrative
and reference documentation in separate documents, the cross-references
won't actually work between them.

8

Michael Droettboom wrote:

Secondly, the ipython console sessions aren't getting syntax highlighted -- it would be nice if they did, particularly to indicate input vs. output. I'll volunteer to look into this -- I've done some pygments customization work in the past and maybe it won't be too difficult.
  

I just committed support for this on the trunk. The usage is not automatic. The reST code must specifically request it using the ..sourcecode directive:

.. sourcecode:: ipython

    In [101]: ax.lines[0]
    Out[101]: <matplotlib.lines.Line2D instance at 0x19a95710>

    In [102]: line
    Out[102]: <matplotlib.lines.Line2D instance at 0x19a95710>

Making this automatic would have required monkey-patching Sphinx -- there doesn't seem to be an API to extend its algorithm to automatically select a syntax highlighter, as I suppose this requirement is somewhat obscure.

Cheers,
Mike

···

--
Michael Droettboom
Science Software Branch
Operations and Engineering Division
Space Telescope Science Institute
Operated by AURA for NASA

9

John Hunter wrote:

···

On Fri, May 23, 2008 at 8:12 AM, Michael Droettboom <mdroe@...31...> wrote:

Personally, I would prefer to see all the names in monospaced type (I find
it much more readable), but the additional markup may be somewhat at odds
with keeping the original ReST source clean. There are also two roads to
take: a) simply putting `` around them, or b) using the Sphinx
cross-referencing constructs, e.g. ":class:`Line2D`".

b) is obviously a lot noisier in the original ReST, but could produce more
useful online documentation. Note, however, that if we put the narrative
and reference documentation in separate documents, the cross-references
won't actually work between them.
    
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?
  

It appears to. See, for example, the :mod:`matplotlib.plab` that gets formatted in monospace in the introduction.

Cheers,
Mike

--
Michael Droettboom
Science Software Branch
Operations and Engineering Division
Space Telescope Science Institute
Operated by AURA for NASA

10

I just committed a few changes so equations can be rendered using the mathpng
extension. The syntax is shown in the documenting_mpl.txt.

···

On Friday 23 May 2008 10:54:52 am John Hunter wrote:

On Fri, May 23, 2008 at 8:12 AM, Michael Droettboom <mdroe@...31...> wrote:
> Personally, I would prefer to see all the names in monospaced type (I
> find it much more readable), but the additional markup may be somewhat at
> odds with keeping the original ReST source clean. There are also two
> roads to take: a) simply putting `` around them, or b) using the Sphinx
> cross-referencing constructs, e.g. ":class:`Line2D`".
>
> b) is obviously a lot noisier in the original ReST, but could produce
> more useful online documentation. Note, however, that if we put the
> narrative and reference documentation in separate documents, the
> cross-references won't actually work between them.

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?

11

I think it might be worth mentioning on Sphinx-dev, there might be some
interest in supporting it. As it is, though, I don't think
".. sourcecode:: ipython" isn't much more distracting than, say:

blah blah::

  :ipython:
  In [101]: ax.lines[0]
  Out[101]: <matplotlib.lines.Line2D instance at 0x19a95710>

  In [102]: line
  Out[102]: <matplotlib.lines.Line2D instance at 0x19a95710>

Darren

···

On Friday 23 May 2008 10:56:47 am Michael Droettboom wrote:

Michael Droettboom wrote:
> Secondly, the ipython console sessions aren't getting syntax highlighted
> -- it would be nice if they did, particularly to indicate input vs.
> output. I'll volunteer to look into this -- I've done some pygments
> customization work in the past and maybe it won't be too difficult.

I just committed support for this on the trunk. The usage is not
automatic. The reST code must specifically request it using the
..sourcecode directive:

.. sourcecode:: ipython

    In [101]: ax.lines[0]
    Out[101]: <matplotlib.lines.Line2D instance at 0x19a95710>

    In [102]: line
    Out[102]: <matplotlib.lines.Line2D instance at 0x19a95710>

Making this automatic would have required monkey-patching Sphinx --
there doesn't seem to be an API to extend its algorithm to automatically
select a syntax highlighter, as I suppose this requirement is somewhat
obscure.

12

For my fellow emacs users:

If you aren't aware of it, there is a reST mode for emacs:

http://docutils.sourceforge.net/tools/editors/emacs/rst.el

In the course of experimenting today, I wrote a few elisp macros (attached) to aid in adding inline cross-references to the code that might be generally useful. By putting the cursor over a particular token, you can easily mark it as a class, function, method, module etc. For example, pressing "C-c c" over the word "Axes" will replace it with ":class:`Axes`".

C-c c : class
C-c m : method
C-c f : function
C-c a : attribute
C-c o : module

Cheers,
Mike

John Hunter wrote:

sphinx-inline-xref.el (756 Bytes)

···

On Fri, May 23, 2008 at 8:12 AM, Michael Droettboom <mdroe@...31...> wrote:

Personally, I would prefer to see all the names in monospaced type (I find
it much more readable), but the additional markup may be somewhat at odds
with keeping the original ReST source clean. There are also two roads to
take: a) simply putting `` around them, or b) using the Sphinx
cross-referencing constructs, e.g. ":class:`Line2D`".

b) is obviously a lot noisier in the original ReST, but could produce more
useful online documentation. Note, however, that if we put the narrative
and reference documentation in separate documents, the cross-references
won't actually work between them.
    
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?

JDH
  
--
Michael Droettboom
Science Software Branch
Operations and Engineering Division
Space Telescope Science Institute
Operated by AURA for NASA

13

Will rest recognize the module this comes from?- I've been using the
full path :class:`matplotlib.lines.Line2D` and when I just want the
Line2D w/o the full path :class:`~matplotlib.lines.Line2D`. I haven't
tested this yet since we don't have the api docs linked in, but this
is how I've been writing...

···

On Fri, May 23, 2008 at 11:59 AM, Michael Droettboom <mdroe@...31...> wrote:

For my fellow emacs users:

If you aren't aware of it, there is a reST mode for emacs:

http://docutils.sourceforge.net/tools/editors/emacs/rst.el

In the course of experimenting today, I wrote a few elisp macros (attached)
to aid in adding inline cross-references to the code that might be generally
useful. By putting the cursor over a particular token, you can easily mark
it as a class, function, method, module etc. For example, pressing "C-c c"
over the word "Axes" will replace it with ":class:`Axes`".

14

John Hunter wrote:

  

For my fellow emacs users:

If you aren't aware of it, there is a reST mode for emacs:

http://docutils.sourceforge.net/tools/editors/emacs/rst.el

In the course of experimenting today, I wrote a few elisp macros (attached)
to aid in adding inline cross-references to the code that might be generally
useful. By putting the cursor over a particular token, you can easily mark
it as a class, function, method, module etc. For example, pressing "C-c c"
over the word "Axes" will replace it with ":class:`Axes`".
    
Will rest recognize the module this comes from?- I've been using the
full path :class:`matplotlib.lines.Line2D` and when I just want the
Line2D w/o the full path :class:`~matplotlib.lines.Line2D`. I haven't
tested this yet since we don't have the api docs linked in, but this
is how I've been writing...
  

From the playing around I've done, it seems that, yes, you do need to fully specify if you're writing from outside of a docstring. However within docstrings, it seems you can refer to other methods in the same class or other classes in the same module by their name only.

(My emacs macros are a little broken because they stop at '.'s, but hopefully I can fix that without going too crazy.)

Cheers,
Mike

···

On Fri, May 23, 2008 at 11:59 AM, Michael Droettboom <mdroe@...31...> wrote:

--
Michael Droettboom
Science Software Branch
Operations and Engineering Division
Space Telescope Science Institute
Operated by AURA for NASA

15

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. But I am
having trouble in that my class links are not recognized, even though
I've added the relevant module to the api_artists.txt file which is
included by api.txt which is included by indext.txt which builds
everything. Any ideas?

JDH

···

On Fri, May 23, 2008 at 9:54 AM, John Hunter <jdh2358@...149...> 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?

16

I just discovered the figure directive:

.. literalinclude:: figures/pyplot_simple.py

.. figure:: figures/pyplot_simple.png
   :scale: 50

   Here's a caption!

Its not obvious in the html output that it is a caption, but in the latex
output it uses the figure environment and so a caption yields a figure
number.

Is there a prefered size for the figures? The html figures are currently a
little large for my taste, and the pdf figures are a little small.

One last thing, I wonder if it would be worth pursuing the ability to include
pdf files in the latex document. Maybe Georg would accept a patch that
attempts to do the right thing if the extension is missing?

Darren

···

On Friday 23 May 2008 02:00:57 pm Michael Droettboom wrote:

John Hunter wrote:
> On Fri, May 23, 2008 at 11:59 AM, Michael Droettboom <mdroe@...31...> wrote:
>> For my fellow emacs users:
>>
>> If you aren't aware of it, there is a reST mode for emacs:
>>
>> http://docutils.sourceforge.net/tools/editors/emacs/rst.el
>>
>> In the course of experimenting today, I wrote a few elisp macros
>> (attached) to aid in adding inline cross-references to the code that
>> might be generally useful. By putting the cursor over a particular
>> token, you can easily mark it as a class, function, method, module etc.
>> For example, pressing "C-c c" over the word "Axes" will replace it with
>> ":class:`Axes`".
>
> Will rest recognize the module this comes from?- I've been using the
> full path :class:`matplotlib.lines.Line2D` and when I just want the
> Line2D w/o the full path :class:`~matplotlib.lines.Line2D`. I haven't
> tested this yet since we don't have the api docs linked in, but this
> is how I've been writing...

From the playing around I've done, it seems that, yes, you do need to
fully specify if you're writing from outside of a docstring. However
within docstrings, it seems you can refer to other methods in the same
class or other classes in the same module by their name only.

(My emacs macros are a little broken because they stop at '.'s, but
hopefully I can fix that without going too crazy.)

17

If a member doesnt contain a docstring, it wont be included by autodoc, at
least by default. You can change this by adding the undoc-members flag:

:mod:`matplotlib.lines`

···

On Friday 23 May 2008 03:02:55 pm John Hunter wrote:

On Fri, May 23, 2008 at 9:54 AM, John Hunter <jdh2358@...149...> 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. But I am
having trouble in that my class links are not recognized, even though
I've added the relevant module to the api_artists.txt file which is
included by api.txt which is included by indext.txt which builds
everything. Any ideas?

=============================

.. automodule:: matplotlib.lines
   :members:
   :undoc-members:

So Line2D was not showing up in the api chapter.

I added that line in the trunk, deleted my build directory, and I can see the
link now.

Darren

--
Darren S. Dale, Ph.D.
Staff Scientist
Cornell High Energy Synchrotron Source
Cornell University
275 Wilson Lab
Rt. 366 & Pine Tree Road
Ithaca, NY 14853

darren.dale@...143...
office: (607) 255-3819
fax: (607) 255-9001
http://www.chess.cornell.edu

18

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

···

On Friday 23 May 2008 03:02:55 pm John Hunter wrote:

On Fri, May 23, 2008 at 9:54 AM, John Hunter <jdh2358@...149...> 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.

19

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.

···

On Fri, May 23, 2008 at 3:00 PM, Darren Dale <darren.dale@...143...> wrote:

On Friday 23 May 2008 03:02:55 pm John Hunter wrote:

On Fri, May 23, 2008 at 9:54 AM, John Hunter <jdh2358@...149...> 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.

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

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

20

No, I was just having a look at that myself. Usually it gives you a little
more to go on, like these which are now fixed except for the last one:

WARNING: <docstring of matplotlib.artist.ArtistInspector.get_aliases>:4:
(ERROR/3) Unexpected indentation.
WARNING: <docstring of matplotlib.lines.unmasked_index_ranges>:17: (ERROR/3)
Unexpected indentation.
WARNING: <docstring of matplotlib.lines.unmasked_index_ranges>:25: (ERROR/3)
Unexpected indentation.
WARNING: /usr/local/src/matplotlib/matplotlib/doc/users_guide/users_guide.txt:7:
(WARNING/2) toctree references unknown document u'customizing'

Could you commit yout customizing.txt?

···

On Friday 23 May 2008 04:12:51 pm John Hunter wrote:

On Fri, May 23, 2008 at 3:00 PM, Darren Dale <darren.dale@...143...> wrote:
> On Friday 23 May 2008 03:02:55 pm John Hunter wrote:
>> On Fri, May 23, 2008 at 9:54 AM, John Hunter <jdh2358@...149...> 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/ap
i_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?