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

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

Replying to Günter Milde:

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.


Can you clarify what you mean?  My point is essentially that (independently
of sphinx/numpydoc, but simply when embedding rst into a python string
literal) there is no way to have a long classifier list that looks good
both at the level of the python source, and at the level of printed string
(as displayed by ``print(docstring)``).

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


This is essentially the approach of "standard" Sphinx docstrings, which are
arguably(?) less legible (at the source level) than both numpydoc and
google style docstrings (see
http://www.sphinx-doc.org/en/stable/ext/napoleon.html#napoleon-marching-toward-legible-docstrings
for discussion).  As a tangent, note that google style docstrings are *not*
rst-compliant (due to the incompatble indent in multiline argument
descriptions), which makes it difficult to decide e.g. what is the correct
syntax when trying to embed a bullet list in an argument description.  It
is for this reason (having well spec'ed rules for including "complex"
syntax items in an argument description) that I'd prefer numpydoc to stay
rst compliant.

Antony

2017-10-04 10:57 GMT-07:00 Antony Lee <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!
>