# [Doc-SIG] Python docs in reST

Fred L. Drake, Jr. fdrake at acm.org
Fri May 27 21:10:49 CEST 2005

On Friday 27 May 2005 12:37, Felix Wiemann wrote:
> 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.

Don't make that assumption.

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

Good so far.

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

Consider the \code{foo\nbar} string!

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

I'm not sure what the use-case is here, but there shouldn't be anything like
this in the Python docs.  This should probably be an "alltt" environment like
this:

\begin{alltt}
This is the \emph{first} line.
This is the \emph{second} line.
\end{alltt}

The line-block syntax in ReST is nice, but I don't know that there's much use
for it in the Python documentation.  We do use alltt and verbatim
environments a lot.

> I'm not gonna try to render a table with its $\backslash$hlines here.
> \end{document}
> ----------------------------------------------------------------------

Yes, tables don't do well in LaTeX.  I'm not so familiar with the ReST syntax
either, but had a hard time with the few I've done in ReST (lines end up
*way* too long; at least that's not a constraint in LaTeX, since I can put
rows on separate lines).  Note that tables in Python documentation tend to be
marked up very differently than in raw 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").

As noted above, the Python documentation style wraps the raw LaTeX table
constructs.  There are reasons for this.  :-)

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

Indeed.  The nice list syntaxes in ReST are a definate benefit.

>   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 don't need to do this directly in standard LaTeX markup; we introduce
specialized list-based environments so they can be marked semantically, and
processing can be applied as needed.

-Fred

--
Fred L. Drake, Jr.   <fdrake at acm.org>