simplemark¶

A small markup language for Python docstrings and argparse help text.

You write a docstring once, wrapped however it looks best in the source file. The reader gets it reflowed to their terminal (60 columns or 200) with the examples and tables left exactly as you typed them, and the parameter names actually distinguishable from the prose around them.

def walk(top, followlinks=False):
    """Directory tree generator.

    For each directory rooted at `top`, yields a **3-tuple**:

        dirpath, dirnames, filenames

    Set *followlinks* to visit symlinks.  See [the docs](https://example.com).
    """

What it is, precisely¶

Simplemark is a subset of CommonMark's constructs, with one narrowed inline rule.

You write Markdown. Headings, [links](url), `code`, **bold**, *italic*, lists, indented examples: all of it means what you expect. Simplemark omits everything a docstring never needed: tables, images, footnotes, raw HTML, block quotes, reference links, nested markup.

The one narrowed rule¶

Emphasis delimiters must be flanked by whitespace or punctuation, so emphasis never happens inside a word. That single change is the difference between a format that works on Python prose and one that does not:

It is a strict narrowing: simplemark never finds emphasis CommonMark would not, so a clean docstring still renders correctly on GitHub. All of these are literal text, with no escaping at all:

*args   **kwargs   f(*args, **kwargs)   10**e   x**y
__init__   _private   a_b_c   *.py   C:\dir   \d+   [start, [stop]]

Measured against the corpus¶

Every docstring in the Python 3.12 standard library, all 7272 of them, through the checker:

Nine tenths of the standard library is already written in simplemark. It just doesn't know it yet.

Small enough to read¶

788 lines of code, no runtime dependencies, linear time, one regular expression in the block grammar. Parsing is total: every string parses, and parse, parse_inline, check and render_text never raise on any input. A docstring cannot crash your help output.

Where to go next¶