[Docutils-users] Multi-line classifiers in definition lists

[Antony L. <ant...@be...>]

Hi all,

Currently, RST specifies that entries in a definition list may be followed
by a series of classifiers all on the same line, as in

    term : classifier one : classifier 2
        Definition

This syntax is used by numpydoc (the de facto docstring standard in the
scientific Python world) to document individual parameters of callables, as
in

    parameter_name : type_of_parameter
        Description of the parameter.

(see
https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt#sections
for details).

In general, this approach yields highly legible raw docstrings, and can
easily be converted into the Sphinx standard field list format (tools to do
so include numpydoc and sphinx.ext.napoleon).

However, it is awkward to include very long parameter "types" (e.g., an
enumeration of allowable string values -- which I know is not strictly a
type, but remains a common API) using this method, due to the restriction
that the classifiers need to stay in one line.  In practice, this means
that it is necessary to use a line continuation in the docstring, either

    parameter_name : some long type \
description
        Description of parameter.

or

    parameter_name : some long type \
                     description
        Description of the parameter.

The first form is ugly in the source, the second form is ugly when the
docstring is viewed as a string (e.g. by pydoc) as all the spaces before
``description`` end up in the literal docstring.  See e.g.
https://github.com/numpy/numpydoc/issues/87 for a longer discussion of the
issue.

While numpydoc can of course invent its own syntax, it would seem
preferable if a standard way to write multi-line classifiers was specified
by the RST standard.  Just checking for indentation is actually a bit
ambiguous, because it is not clear how to parse

    a : b
        c

(is ``c`` a continuation or a description?).  A possibility would be to
support backslashed-line continuations at the RST level, so the Python
docstring would look like

    parameter_name : some long type \\
                     description
        Description of the parameter

but RST would see a single backslash and know what to do; or require that
continued classifier lines start also with ``: ``:

    parameter_name : some long type
                   : description
        Description of the parameter

Neither option is strictly fully back-compatible, but I hope one of them,
or some similar solution, can be adopted.

Antony Lee

PS: As suggested on the docutils mailing list page, I am not subscribed to
the list, so please CC me in the reply.  Thanks!