[Doc-SIG] Python docs in reST

[Felix Wiemann]

Ian Bicking wrote:

> (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)

We're both subscribed.  (I read this list with lower priority than the
Docutils lists, though.)

> * I believe ReST markup is a superset of the conventional Python
> Latex.

Not yet.  We need to have some custom code specially designed for Python
standard documentation.  ReST isn't capable of expressing all things
that can be expressed in Python-doc-LaTeX yet.

> * ReST is a superset, so there's a bunch of things that I think are
> much more easily expressed there than in the Latex.

When it comes to comparing reST and LaTeX, I'd be wary of using terms
like "superset" because the two languages cover different scopes.

> (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.

As long as you need to mix LaTeX and reST standard-doc sources, making
Docutils output Python-doc-LaTeX seems like the most viable approach.

> It's readily extensible on the local level by adding new directives
> and inline roles.

Adding new directives isn't possible at the moment.  (Even though that
might be a good idea maybe.)

> * There's no tools that I know of to generate ReST.  I think it would
> have to be based on heuristics, with manual editing.

Theoretically you could write a full-blown reST-writer, but hacking
together a prototype might be not too difficult, if you leave out
tables.

> I think the warnings are pretty good, though, so I think this is
> doable without having to carefully proofread all of the output.

Yes.

> * I personally find writing ReST pleasant, but I think Michael is
> right that it's not the Latex that keeps people from contributing.

Dunno.  For me, as someone who has both a running LaTeX system and some
LaTeX knowledge, it might indeed keep me from contributing, partly
because it takes more than just typing "latex" to get the files
processed, partly because I don't like LaTeX as an input format.

> [...] Well, does anyone write docs on a whim?

If not, reST is a great opportunity to change that.  :-)

For the Docutils project, writing docs is quite easy indeed, because
they're all in reST.

-- 
For private mail please ensure that the header contains 'Felix Wiemann'.

http://www.ososo.de/