Skip to content

Quick start

Three functions do everything: parse, render_text, check.

Every example on this page is executed when the documentation is built, so the outputs below are real.

Render a docstring

quickstart.py:

def fact(n, base=10):
    """Compute the factorial of `n`.

    Raises `ValueError` if `n` is negative.  The *base* argument
    only affects how the result is formatted, not how it is computed.

    Example:

        >>> fact(5)
        120
    """

Parse it, then render it to whatever width you have:

python -c "
import quickstart, simplemark
doc = simplemark.parse(quickstart.fact.__doc__)
print(simplemark.render_text(doc, width=52, style='none'))
"

Compute the factorial of 'n'.

Raises 'ValueError' if 'n' is negative.  The base
argument only affects how the result is formatted,
not how it is computed.

Example:

    >>> fact(5)
    120

Three things happened there, and each is deliberate:

  • The prose reflowed to 52 columns. The source was wrapped for the source file; the output is wrapped for the reader.
  • The example did not reflow. Verbatim blocks are preserved exactly.
  • Code spans became 'quoted' and emphasis lost its markers. On a terminal with no styling, the semantic distinction survives and the decoration does not. See rendering.

The same docstring, narrower

Nothing changes but the number:

python -c "
import quickstart, simplemark
doc = simplemark.parse(quickstart.fact.__doc__)
print(simplemark.render_text(doc, width=34, style='none'))
"

Compute the factorial of 'n'.

Raises 'ValueError' if 'n' is
negative.  The base argument only
affects how the result is
formatted, not how it is computed.

Example:

    >>> fact(5)
    120

The example still has not moved. That is the whole point of the format.

Check for problems

check returns a list of diagnostics and never raises:

python - <<'EOF'
import simplemark
for d in simplemark.check("Uses 10**e and x**y internally."):
    print(d.severity.value, d)
EOF

commonmark 1:1: CM001 CommonMark reads some of these delimiters as emphasis

That does not stop anything rendering. It says GitHub will find emphasis in x**y that simplemark leaves alone; the arithmetic is safe here, and would be mangled there.

Legacy conventions are reported separately, and only when asked for:

python - <<'EOF'
import simplemark
legacy = "Example::\n\n    code()\n"
print("default:", simplemark.check(legacy))
for d in simplemark.check(legacy, compat=True):
    print("compat: ", d)
EOF

default: []
compat:  1:8: L001 trailing '::' is reStructuredText; write ':'

From the shell

The same thing without writing any Python:

printf 'Compute `n` factorial.\n\nExample:\n\n    >>> fact(5)\n    120\n' > doc.txt
python -m simplemark --width 40 --style none doc.txt

Compute 'n' factorial.

Example:

    >>> fact(5)
    120

And in CI, where a non-zero exit means an error was found:

python -m simplemark --check doc.txt && echo "clean"

clean

Next