[IPython-dev] Doc guidelines

Fernando Perez fperez.net@gmail....
Fri Jul 4 17:36:32 CDT 2008


Hi all,

I'll be committing soon the testing stuff, and because of this I've
been looking again at the docs directories.  We now have merged docs
from various sources (hand-written reST from ipython1, converted reST
from the old lyx sources, by various people, etc) and I realized that
we have a mix of lots of styles.  Fortunately reST is fairly flexible
so we don't need to go on a major cleanup expedition, but I think that
moving forward we should try to also keep a consistent formatting
style in reST for the same reasons that consistent style in source
code is a good idea when working in a team.

Rather than coming up with any ad-hoc rules of our own, we might as
well use what everyone else related to us is using.  The sphinx
project itself has some information on the basic use of reST with
sphinx here:

http://sphinx.pocoo.org/contents.html

and I'd suggest that we also follow the advice of what matplotlib is doing:

http://matplotlib.sourceforge.net/doc/html/devel/documenting_mpl.html

MPL has recently gone on a *major* documentation effort, and we might
as well share the tools they've added on top of basic sphinx.  We
obviously don't need the math rendering, but things like
ipython-specific highlighting might come in handy :)

Finally, a few things I noticed that I'd like to propose as standard
practice, that aren't mentioned above.  They basically boil down to
re-using PEP-8 conventions in reST when applicable:

- No hard tabs, 4 spaces for indenting code blocks and the like.
While having a mix of tabs and spaces won't cause bugs like it can in
python so easily, it's still likely to produce in the long run
messy-to-edit sources since different people will  do different
things.  It seems best to just stick to one solution consistent with
the rest, else we'll be forever dealing with mixups due to how
everyone had their editor set on any given day.

- Lines to 78 chars or so.  There are lots of unwrapped paragraphs,
these tend to wrap differently depending on the editor used, so it's
probably best to stick to regular line-broken paragraphs as for python
source.

- Any code block meant to represent a command line should have '$'
markers.  I think I'll be able to build support for all reST in the
testing stuff, and this might allow us to mix commands meant for the
shell with python sources without confusing the testing code nor
making the parsing code a complete nightmare.  (the sources are
already pretty good in doing this, though I've seen a few spots where
we've missed it).

I can't think of anything else for now.  But if you all agree on this,
we'll put it in the guidelines and we can update things as we go.

Cheers,

f


More information about the IPython-dev mailing list