[Doc-SIG] Python docs in reST

[Ian Bicking]

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 
tries it.

* 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 
actual documentation.

* 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