[Doc-SIG] Python docs in reST

Felix Wiemann Felix.Wiemann at gmx.net
Fri May 27 18:37:27 CEST 2005


Fred L. Drake, Jr. wrote:

> Felix Wiemann wrote:
>
>> * We want to have **well-readable** documentation source.
>
> We have that now.  Not ReST, but its very readable.

I just quickly wrote up a short LaTeX document to test that.  It's not
the Python doc format but just a normal LaTeX document, but I presume it
won't make much of a difference.

----------------------------------------------------------------------
\documentclass{article}
\begin{document}
\begin{verbatim}
>>> print "foo\nbar"
foo
bar
>>>
\end{verbatim}

Consider the \texttt{foo$\backslash$nbar} string!

\vspace{1em}\noindent\texttt{%
This is the \emph{first} line.\\
This is the \emph{second} line.}
\vspace{1em}

I'm not gonna try to render a table with its $\backslash$hlines here.
It's \emph{completely} unreadable, IMO.
\end{document}
----------------------------------------------------------------------

Now have a look the same thing as reST:

----------------------------------------------------------------------
>>> print "foo\nbar"
foo
bar
>>>

Consider the ``foo\nbar`` string!

.. parsed-literal::

    This is the *first* line.
    This is the *second* line.

I'm not gonna try to render a table with its \\hlines here.  It's
*completely* unreadable, IMO.
----------------------------------------------------------------------

I find the reST document shorter and more readable than the LaTeX
document.  (I will admit though that some of that readability gets lost
if you explicitly mark up function names and the like.)

Furthermore, and that's where my example stops, there are many
block-level constructs which are extremely simple in reST but require
significant markup in LaTeX:

* In reST I can insert tables as simple tables, grid tables (with
  support from Emacs!), list-tables and CSV-tables.  In LaTeX there is a
  "tabular" environment whose syntax I have to look up everytime I use
  it, and the table contents aren't nicely viewable in LaTeX (because
  they're interspersed with "&", "\\" and "\hline").

* There are some handy list-like constructs in reST, e.g. field lists or
  definition lists.  I just type

  :Field name: Field body

  or

  Term : classifier
     Associated paragraph.

  and I have really nice output in HTML and LaTeX.

  In LaTeX I simply wouldn't know how to do this off the top of my head.
  It's possible of course, but it's just not simple and straightforward,
  and for somebody who doesn't have a LaTeX reference at hand it must be
  really difficult.

>> * We want to get **flexibility** in that we can modify the parsed
>>   document using Python code.
>
> Is this a goal, or is this a means to an end?

Flexibility is a goal by itself, IMO.

>> * We want an **easy-to-use** documentation system.  Any documentation
>>   should be renderable by typing "sometool.py input.txt output.html".
>>   Getting multi-document output should be similarly easy.
>
> Again, I think we have this now.  "mkhowto input.tex" is pretty 
> straightforward.

But it doesn't work out of the box and it's not easy to install.

    ~ $ cd source/python/python/dist/src/Doc/lib/

    ~/source/python/python/dist/src/Doc/lib $ locate mkhowto
    /home/felix/source/python/python/dist/src/Doc/tools/mkhowto

    ~/source/python/python/dist/src/Doc/lib $ /home/felix/source/python/python/dist/src/Doc/tools/mkhowto libbase64.tex
    +++ TEXINPUTS=/home/felix/source/python/python/dist/src/Doc/lib:.:/home/felix/tex:/var/home/felix/source/python/python/dist/src/Doc/paper-letter:/var/home/felix/source/python/python/dist/src/Doc/texinputs:
    +++ latex libbase64
    *** Session transcript and error messages are in /home/felix/source/python/python/dist/src/Doc/lib/libbase64/libbase64.how.
    *** Exited with status 1.
    [snipped error messages]

Doc/README doesn't tell me what to install to make it work.

Installing Docutils is very easy, OTOH.  Download, unpack, click
install.py.

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

http://www.ososo.de/



More information about the Doc-SIG mailing list