Re: Multi-line classifiers in definition lists

Oops, I meant to reply-all:

On Oct 7, 2017 10:48 PM, "David Goodger" <[email protected]> wrote:

I like the idea of backslash-escape line continuations at the reST level.
It's a general purpose change that could help in other areas too. It might
have side effects though.

Can't work on it right now: on vacation, cycle touring. I'll take a look
when I get back in a week or so.

David Goodger


On Oct 4, 2017 1:37 PM, "Antony Lee" <[email protected]> wrote:

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_DOCUMEN
T.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!

------------------------------------------------------------
------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
_______________________________________________
Docutils-users mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/docutils-users

Please use "Reply All" to reply to the list.

------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot