[Doc-SIG] Python docs in reST

[Felix Wiemann]

Martin Blais wrote:

> Michael Foord wrote:
>
>> Felix Wiemann wrote:
>> 
>>> Ideas:
>>>
>>> * We want to have **well-readable** documentation source.
>
> hmmm...  the current latex markup is as simple as it can be.  it's got
> a word, and some form of delimiters, e.g. \function{foo}.  i don't
> feel that `foo`:function: is all that much better.

No, indeed not.  However, there are other differences I outlined in
<http://article.gmane.org/gmane.comp.python.documentation/947>.

> rest allows you to view the input files directly, as output (ascii
> output = input).  this assumes that the markup is kept to its *bare
> minimum*.  this is an *explicit* reason for creating rest in the first
> place.  the more we are talking about adding markup on rest, the
> stranger this whole discussion is becoming.

First of all, just to avoid misunderstandings, I don't think roles like
:function: or :class: will be added to standard-reST.  If it all, it
will be an extension (possibly shipped with the Docutils distribution
though) which must be explicitly activated (probably from inside the
reST document, like ".. extension:: python-doc").

While the goal of reST is to avoid explicit markup, IMO it's fine to use
explicit markup where considered necessary and it doesn't make reST less
useful.

> [...] with rest, the source has to more or less "look like" the
> output.

That's a goal, but it's not a requirement: You can still use reST if the
output doesn't look exactly like the reST source.

And even if you mark up function names, parameters and class names,
still a lot of reST's WYSIWYG and simplicity is retained, and that's a
big advantage over LaTeX.

> IMHO the worst thing that could happen is that one day I open a text
> file supposedly writtne in rest, and that i can't understand it
> because i have to learn what all that new markup is all about.

As I wrote above, all that explicit markup won't be part of
standard-reST.

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

http://www.ososo.de/