An Alternative Python Reference: Markup

Fredrik Lundh | January 2006

(This page belongs to the Alternative Python Reference project.)

Markup

The tools use a preliminary markup format, based on basic HTML with JavaDoc tags for semantic markup. JavaDoc is widely used, and works well for reference documentation which tends to use mostly library/language related semantic markup. And if you strip down HTML and use other markup to create links, it’s not much left. Only a simple tag here and there.

In a full JavaDoc system, the tools gets the program structure from the source code. In this system, the tools derive structure from special section tags instead.

@@module __builtin__

Built-in functions, exceptions, and other objects.

@@function len(obj)

Returns the number of items in a sequence or mapping.

@@module, @@function etc. are section tags. All the text inside a section describe one target object (in this case, the len function) inside a target scope (in this case, the builtin namespace).

Standard PythonDoc markup can be used to add more details to a section. If given, the @def directive overrides the signature given in the section marker.

@@function range

This is a versatile function to create lists containing
arithmetic progressions.  It is most often used in {@link
python:for} loops.  All arguments must be plain integers.

<p> The full form returns a list of plain integers [{@var
start}, {@var start} + {@var step}, {@var start} + 2 * {@var
step}, ...].
If {@var step} is positive, the last element is the largest
such value less than {@var stop};
if {@var step} is negative, the last element is the smallest
value greater than {@var stop}.

<p> In the abbreviated form, {@var start} is set to 0, and
{@var step} to 1.

    @def range(stop)
    @def range(start, stop, step=1)
    @param start The start value.  Defaults to 0.
    @param stop The stop value.  This is not included in the
         returned sequence.
    @param step The non-zero step value.  Defaults to 1.
    @return A list containing an integer sequence.
    @raises ValueError If {@var step} is zero.

The {@var} directive is used to mark arguments inside a function or method description. The inline {@link} directive is used to refer to other target objects.

Notes

The translator uses inline @link elements to mark all known reference targets. It’s up to the renderer to decide what references to turn into hyperlinks in the resulting document. An HTML renderer may for example link only the first occurrence of each item within a section, or use CSS to make subsequent links less prominent (unless the user hovers over them).

{@var}, {@samp} etc. are non-standard tags. Use <var> instead?

Using {@link} for external links (http:) is overkill. Use <a> instead!