On Thursday 22 May 2008 02:05:14 pm John Hunter wrote: > On Thu, May 22, 2008 at 12:48 PM, Darren Dale <[EMAIL PROTECTED]> wrote: > > 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 ------------------------------------------------------------------------- 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 https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
