ReStructured Text

Synopsis supports the full set of ReStructuredText markup (See http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html). In order to process ReST docstrings, docutils 0.4 or higher must be installed. If Docutils is not installed, ReST docstrings will be rendered as plaintext.

ReST provides a wide variety of markup that allows documentation strings to be formatted in a wide variety of ways. Among the many features are different list styles, tables, links, verbatim blocks, etc.

Interpreted text is used to mark up program identifiers, such as the names of variables, functions, classes, and modules. Synopsis will attempt to look them up in its symbol table, and generate suitable cross-references.

Example C.2. C++ code snippet using ReST-style comments.

//. The Nurbs class. It implements a nurbs curve
//. for the given order. It is a very powerful
//. and flexible curve representation. For simpler
//. cases you may prefer to use a `Paths::Bezier` curve.
//.
//. While non-rational curves are not sufficient to represent a circle,
//. this is one of many sets of NURBS control points for an almost uniformly 
//. parameterized circle:
//.
//. +--+----+-------------+
//. |x |  y | weight      |
//. +==+====+=============+
//. |1 |  0 | 1           |
//. +--+----+-------------+
//. |1 |  1 | `sqrt(2)/2` |
//. +--+----+-------------+
//. |0 |  1 | 1           |
//. +--+----+-------------+
//. |-1|  1 | `sqrt(2)/2` |
//. +--+----+-------------+
//. |-1|  0 | 1           |
//. +--+----+-------------+
//. |-1| -1 | `sqrt(2)/2` |
//. +--+----+-------------+
//. |0 | -1 | 1           |
//. +--+----+-------------+
//. |1 | -1 | `sqrt(2)/2` |
//. +--+----+-------------+
//. |1 |  0 | 1           |
//. +--+----+-------------+
//.
//. The order is three, the knot vector is {0, 0, 0, 1, 1, 2, 2, 3, 3, 4, 4, 4}.
//. It should be noted that the circle is composed of four quarter circles,
//. tied together with double knots. Although double knots in a third order NURBS
//. curve would normally result in loss of continuity in the first derivative,
//. the control points are positioned in such a way that the first derivative is continuous.
//. (From Wikipedia_ )
//.
//. .. _Wikipedia: http://en.wikipedia.org/wiki/NURBS
//.
//. Example::
//.
//.   Nurbs<3> circle;
//.   circle.insert_control_point(0, Vertex(1., 0.), 1.);
//.   circle.insert_control_point(0, Vertex(1., 1.), sqrt(2.)/2.);
//.   ...
//.
        

To see how this is formatted please refer to the DocBook example.