epytext_demo

Scope and Purpose

Sample package for describing and demonstrating pydoctor HTML API rendering for Epytext based documentation.

Many examples are copied from the epytext manual.

Try to keep the example as condensed as possible.

• Make it easy to review HTML rendering.
• Cover all epytext markup. Like the usage of list with various indentation types.
• Have it build as part of our continuous integration tests. To ensure we don't introduce regressions.

Lists

Epytext supports both ordered and unordered lists. A list consists of one or more consecutive list items with the same indentation. Each list item is marked by a bullet. The bullet for unordered list items is a single dash character (-). Bullets for ordered list items consist of a series of numbers followed by periods, such as 12. or 1.2.8..

Ordered list example:

1. This is an ordered list item.
2. This is a another ordered list item.
3. This is a third list item. Note that the paragraph may be indented more than the bullet.

Example of unordered list:

• This is an ordered list item.
• This is a another ordered list item.

Example of complex list:

1. This is a list item.

   • This is a sublist.
   • The sublist contains two items.
     • The second item of the sublist has its own sublist.

2. This list item contains two paragraphs and a doctest block.

   >>> print 'This is a doctest block'
   This is a doctest block
   

   This is the second paragraph.

Literal Blocks

Literal blocks are used to represent "preformatted" text. Everything within a literal block should be displayed exactly as it appears in plaintext.

• Spaces and newlines are preserved.
• Text is shown in a monospaced font.
• Inline markup is not detected.

Literal blocks are introduced by paragraphs ending in the special sequence ::. Literal blocks end at the first line whose indentation is equal to or less than that of the paragraph that introduces them.

The following is a literal block:

    Literal /
           / X{Block}

Doctest Blocks

• contain examples consisting of Python expressions and their output
• can be used by the doctest module to test the documented object
• begin with the special sequence >>>
• are delimited from surrounding blocks by blank lines
• may not contain blank lines

The following is a doctest block:

>>> print (1+3,
...        3+5)
(4, 8)
>>> 'a-b-c-d-e'.split('-')
['a', 'b', 'c', 'd', 'e']

This is a paragraph following the doctest block.

Basic Inline Markup

Inline markup may be nested; and it may span multiple lines.

Epytext defines four types of inline markup that specify how text should be displayed:

• Italicized text
• Bold-faced text
• Source code
• Math

Without the capital letter, matching braces are not interpreted as markup: my_dict={1:2, 3:4}.

URLs

The inline markup construct text is used to create links to external URLs and URIs. 'text' is the text that should be displayed for the link, and 'url' is the target of the link. If you wish to use the URL as the text for the link, you can simply write "url". Whitespace within URL targets is ignored. In particular, URL targets may be split over multiple lines. The following example illustrates how URLs can be used:

• www.python.org
• http://www.python.org
• The epydoc homepage
• The Python homepage
• Edward Loper

Symbols

Symbols are used to insert special characters in your documentation. A symbol has the form S{code}, where code is a symbol code that specifies what character should be produced.

Symbols can be used in equations: ∑α/x ≤ β

← and ← both give left arrows. Some other arrows are →, ↑, and ↓.

Escaping

Escaping is used to write text that would otherwise be interpreted as epytext markup.

Escaped text has the form E{code}, where code is an escape code that specifies what character should be produced.

If the escape code is a single character (other than '{' or '}'), then that character is produced. For example, to begin a paragraph with a dash (which would normally signal a list item), write '-'. In addition, two special escape codes are defined: '{' produces a left curly brace ('{'); and '}' produces a right curly brace ('}').

This paragraph ends with two colons, but does not introduce a literal block::

- This is not a list item.

Escapes can be used to write unmatched curly braces: }{