Re: Multi-line classifiers in definition lists

On 2017-10-04, Antony Lee 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_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.

Are the docstrings also used with Docutils or only with Sphinx?

Maybe it suffices to have the standard way not specified but compatible with
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.

Another option is a "type" role as alternative markup for long types::

.. role:: type

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

Numpydoc and sphinx.ext.napoleon could then implement a transform that
converts the result to be identical to the simple syntax for short "types".

Günter


------------------------------------------------------------------------------
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.