[Doc-SIG] Python docs in reST?

[Torsten Bronger]

Hallöchen!

Bill Janssen <janssen at parc.com> writes:

>> LaTeX seems to be a we-want-to-get-rid-of-it, and reST is still not
>> really ready.
>
> I decided to do the documentation for my latest project, UpLib, in
> reST, to see how well it works.  My conclusion is that it probably
> will never be ready to document Python, because the design goal of
> making the reST source read like text conflicts with the goal of
> making it functional enough to document a large system.

I'm not so pessimistic.  I think that only a few constructs are
missing to make it suitable for large projects (inclusion and
interlinks).  But apparently this is already being tackled.

For non-Python user guides I use Texinfo.  What I really miss is
Texinfo's @deffn for explaining functions etc.  Yes, I know
<http://docutils.sourceforge.net/docs/dev/semantics.html>, but it
doesn't solve this issue.  reST lacks a standard means of defining
function/method signatures, return values, exceptions etc.  (Similar
structures are needed for classes.)

I use field lists at the moment.  That's okay, but it's not real
logical markup since the reST interpreter has no chance to recognise
it as a function definition.  Besides, its pdf and HTML results are
poor.

Other missing things include standardised meta info, i18n (including
encodings), formulae (a well-defined subset of LaTeX would be good),
and a meta standard for how to use "interpreted text".

> [...]
>
> [...] but next time I'll probably use a simple text markup
> language like troff with an appropriate macro package, or better
> yet runoff.

Do you really think that troff is suitable for large, modern
documentation?  How many people would have to learn it?  How easy is
it to install it on Windows?  How good are the PDFs generated from
it?  How is it converted to HTML?  (I don't know troff very well, as
you can see.  ;)

Tschö,
Torsten.

-- 
Torsten Bronger, aquisgrana, europa vetus