> You're right, that sounds easier. Here's a taste, it has a bit taken from
> the users guide, I marked up the CODING_GUIDE, and I used the autodoc
> extension to document the API of texmanager and dviread:
How do you envision putting this together? Will each of these
documents (eg CODING_GUIDE) live as separate rest files and are then
included in one doc?
We have a lot of flexibility here. I prefer to pull from a few smaller
documents using rest include statements or table of contents directives.
Ipython, on the other hand, has the whole guide included in one file.
I don't think we will want to have one master
PDF for the user's guide, developer's guide and api docs (the
autogenerated api docs at http://matplotlib.sf.net/api.pdf are 560
pages along).
Ok. It is easy enough to break them up into separate documents. I'll work on
it this afternoon. Should we have a separate developers guide, or could it be
included in the users guide?
Did you do any rest conversion of the texmanager and
dviread, or did autodoc do everything?
I had to do some minor modifications to make sure the docstrings were valid
rest: proper indentation is important, and * is used to indicate emphasis, so
any references to *args or **kwags had to be changed to ``*args`` and
``**kwargs`` (I didnt like \*\*kwargs, its too intrusive for reading the
plain text).
I'd like to get a feel for
what the rest markup of the docstrings will look like.
Here is the docstring for the texmanager module:
"""
This module supports embedded TeX expressions in matplotlib via dvipng
and dvips for the raster and postscript backends. The tex and
dvipng/dvips information is cached in ~/.matplotlib/tex.cache for reuse
between
sessions
Requirements:
* latex
* \*Agg backends: dvipng
* PS backend: latex w/ psfrag, dvips, and Ghostscript 8.51
(older versions do not work properly)
Backends:
* \*Agg
* PS
* PDF
For raster output, you can get RGBA numpy arrays from TeX expressions
as follows::
texmanager = TexManager()
s = '\\TeX\\ is Number \\\\displaystyle\\\\sum\_\{n=1\}^\\\\infty\\\\frac\{\-e^\{i\\pi\}\}
\{2^n\}!'
Z = self.texmanager.get_rgba(s, size=12, dpi=80, rgb=(1,0,0))
To enable tex rendering of all text in your matplotlib figure, set
text.usetex in your matplotlibrc file (http://matplotlib.sf.net/matplotlibrc)
or include these two lines in your script::
from matplotlib import rc
rc('text', usetex=True)
"""
I am really amazed at how much can be done with so little. For example, near
the end of that docstring, two colons followed by a blank line and then an
indented block indicates a block of source code.
In any case, this is exciting, since I am eager to have a nice rest
based doc system. You might want to look at incorporating the three
rest docs in the doc subdir: artist_api_tut.txt,
event_handling_tut.txt and devel/add_new_projection.rst since these
are already done.
Ok, they are included now:
http://dale.chess.cornell.edu/~darren/temp/matplotlib/index.xml
and http://dale.chess.cornell.edu/~darren/temp/matplotlib/Matplotlib.pdf
I guess we also need to standardize on rst vs txt
extensions. I think txt is friendlier to windoze users, and I have my
emacs to use rest mode for *.txt
(require 'rst)
(autoload 'rst-mode "rst-mode" "mode for editing reStructuredText
documents" t) (setq auto-mode-alist
(append '(
("\\.txt$" . rst-mode)
("\\.rst$" . rst-mode)
("\\.rest$" . rst-mode)) auto-mode-alist))
I prefer .rst, it makes it clear that there is a specific markup, which could
be overlooked by the uninitiated contributer. But I don't have a strong
opinion.
As you as you can, commit a working directory for the doc build and
I'll help with some of the conversion of the existing docs to rest.
We can split up the user's guide chapters, etc...
Sounds good. I'll work on splitting the docs and make the commit this
afternoon. Before I commit, could we have a ruling on whether the developers
guide should be included in the users guide, and should we use .rst or .txt
extensions? (sphinx wants one or the other.)
Darren
···
On Thursday 22 May 2008 02:05:14 pm John Hunter wrote:
On Thu, May 22, 2008 at 12:48 PM, Darren Dale <darren.dale@...143...> wrote: