[Doc-SIG] Python docs in reST
ianb at colorstudy.com
Wed May 18 20:21:14 CEST 2005
Skip Montanaro wrote:
> >> 1. reference docs: ...
> >> 2. user documentation: ...
> Ian> I think that's a good distinction. And like several people I'm not
> Ian> very interested in 1.
> Ah, but I started this thread thinking about #1. <wink>
Well, not the #1 that Martin described (epydoc-like). The Python
documentation is a perfect example of #2 -- documentation written
completely by hand that provides a structured and concise description of
a module. I shudder to think about what #1 would look like for the
standard library. Well, that's not fair, I can see exactly what it
looks like: http://epydoc.sourceforge.net/stdlib/ -- maybe "shuddering"
isn't really appropriate (it's not that bad), but it's not at all like
the reference docs we know and love.
> FYI, while #2 is important, I'm still interested in this. I'm particularly
> interested in being able to replace latex2html with something more flexible
> that would allow relatively easy experimentation with the online
> presentation of the core documentation.
Well, getting back to your original question about ReST (I've also
copied David Goodger and Felix Wiemann, as they might have more to say
about this and I'm not sure if they are tracking this list)...
* I believe ReST markup is a superset of the conventional Python Latex.
I know a couple people worked on this at PyCon 2004, and they seemed
to feel that local roles were the only missing part (to specifically
mark a word as being a class name, for instance), and that was added to
docutils a while ago in response. This doesn't address linking,
indexing, or the build process -- just the local markup.
* ReST is a superset, so there's a bunch of things that I think are much
more easily expressed there than in the Latex. (Note: I have no idea
what the actual Latex looks like, I only say this from familiarity with
its output ;) The problem with this is that it may be hard to mix
documents generated from the two sources and keep a consistent style.
* There's no build process that would apply. This doesn't seem like a
huge task, nor one that can really be addressed until someone actually
* Interlinking documents may be difficult. ReST documents can't easily
be merged or separated (from what I can tell), and there's no support
for abstract links (you can only link internally or to concrete files).
These are acknowledged problems with ReST, so there might ideas or
even code to address this.
* I'm not sure about indexing -- there's markup to express indexable
terms (I believe), but I don't know if there's tools that actually make
use of that.
* That said, some of its internal-to-the-document indexing is better.
It creates lots of anchors allowing deeper links and the contents
headers are often useful. It's readily extensible on the local level by
adding new directives and inline roles.
* There's no tools that I know of to generate ReST. I think it would
have to be based on heuristics, with manual editing. I think the
warnings are pretty good, though, so I think this is doable without
having to carefully proofread all of the output.
* I personally find writing ReST pleasant, but I think Michael is right
that it's not the Latex that keeps people from contributing.
Personally, I think it has a lot to do with an intimidation factor;
standard library docs are implicitly authoritative, so you don't write
docs on a whim. Well, does anyone write docs on a whim? Anyway, if I
was to analyze my own non-contribution, that'd probably be the reason.
Anyway, I think commenting and annotation systems -- while often
annoying and messy -- do offer a middleground for contributors. For the
most part these could be applied to the current system; but ReST would
make it easier, and has (some) more potential for streamlining the
integration process, integrating comments and annotations into the
* OTOH, complicated build tools are death to building a group of
contributors -- it makes a huge difference, because contributors are
grown over time, most don't start with the intention to be serious
contributors. The offer to convert documents doesn't necessarily make
its way to the people who would take you up on it.
Ian Bicking / ianb at colorstudy.com / http://blog.ianbicking.org
More information about the Doc-SIG