[matplotlib-devel] Emacs reST tools (was: Re: future of mpl documentation)

[Michael D. <md...@st...>]

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:
> On Fri, May 23, 2008 at 8:12 AM, Michael Droettboom <md...@st...> 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