 |
 |
 |
Documenting Python |  |
 |
|
There are some things that an author of Python documentation needs to know about LATEX syntax.
A comment is started by the ``percent'' character ("%") and continues through the end of the line and all leading whitespace on the following line. This is a little different from any programming language I know of, so an example is in order:
This is text.% comment
This is more text. % another comment
Still more text.
The first non-comment character following the first comment is the letter "T" on the second line; the leading whitespace on that line is consumed as part of the first comment. This means that there is no space between the first and second sentences, so the period and letter "T" will be directly adjacent in the typeset document.
Note also that though the first non-comment character after the second comment is the letter "S", there is whitespace preceding the comment, so the two sentences are separated as expected.
A group is an enclosure for a collection of text and commands which encloses the formatting context and constrains the scope of any changes to that context made by commands within the group. Groups can be nested hierarchically. The formatting context includes the font and the definition of additional macros (or overrides of macros defined in outer groups). Syntactically, groups are enclosed in braces:
{text in a group}
An alternate syntax for a group using brackets, [...], is
used by macros and environment constructors which take optional
parameters; brackets do not normally hold syntactic significance.
A degenerate group, containing only one atomic bit of content,
does not need to have an explicit group, unless it is required to
avoid ambiguity. Since Python tends toward the explicit, groups
are also made explicit in the documentation markup.
Groups are used only sparingly in the Python documentation, except for their use in marking parameters to macros and environments.
A macro is usually a simple construct which is identified by name and can take some number of parameters. In normal LATEX usage, one of these can be optional. The markup is introduced using the backslash character ("\"), and the name is given by alphabetic characters (no digits, hyphens, or underscores). Required parameters should be marked as a group, and optional parameters should be marked using the alternate syntax for a group.
For example, a macro named ``foo'' which takes a single parameter would appear like this:
\name{parameter}
A macro which takes an optional parameter would be typed like this when the optional paramter is given:
\name[optional]
If both optional and required parameters are to be required, it looks like this:
\name[optional]{required}
A macro name may be followed by a space or newline; a space
between the macro name and any parameters will be consumed, but
this usage is not practiced in the Python documentation. Such a
space is still consumed if there are no parameters to the macro,
in which case inserting an empty group ({}) or explicit
word space ("\ ") immediately after the macro name helps to
avoid running the expansion of the macro into the following text.
Macros which take no parameters but which should not be followed
by a word space do not need special treatment if the following
character in the document source if not a name character (such as
punctuation).
Each line of this example shows an appropriate way to write text which includes a macro which takes no parameters:
This \UNIX{} is followed by a space.
This \UNIX\ is also followed by a space.
\UNIX, followed by a comma, needs no additional markup.
An environment is a larger construct than a macro, and can be used for things with more content than would conveniently fit in a macro parameter. They are primarily used when formatting parameters need to be changed before and after a large chunk of content, but the content itself needs to be highly flexible. Code samples are presented using an environment, and descriptions of functions, methods, and classes are also marked using environments.
Since the content of an environment is free-form and can consist of several paragraphs, they are actually marked using a pair of macros: \begin and \end. These macros both take the name of the environment as a parameter. An example is the environment used to mark the abstract of a document:
\begin{abstract}
This is the text of the abstract. It concisely explains what
information is found in the document.
It can consist of multiple paragraphs.
\end{abstract}
An environment can also have required and optional parameters of its own. These follow the parameter of the \begin macro. This example shows an environment which takes a single required parameter:
\begin{datadesc}{controlnames}
A 33-element string array that contains the \ASCII{} mnemonics for
the thirty-two \ASCII{} control characters from 0 (NUL) to 0x1f
(US), in order, plus the mnemonic \samp{SP} for the space character.
\end{datadesc}
There are a number of less-used marks in LATEX which are used to enter non-ASCII characters, especially those used in European names. Given that these are often used adjacent to other characters, the markup required to produce the proper character may need to be followed by a space or an empty group, or the markup can be enclosed in a group. Some which are found in Python documentation are:
| Character | Markup |
|---|---|
| ç | \c c |
| ö | \"o |
| ø | \o |
|
|
|
Documenting Python | |
|
|