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

[Guenter M. <mi...@us...>]

On 2017-10-08, Antony Lee wrote:

> Replying to Günter Milde:

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

>From the context below, it seems the docstrings are only used as-is or
with Sphinx, not with standard Docutils.
I am asking, because Sphinx extends the rST syntax with additional roles
and directives.

>> Maybe it suffices to have the standard way not specified but
>> compatible with the rST standard.

> Can you clarify what you mean?

The `napoleon documentation`__ says:

  ReStructuredText is great, but it creates visually dense, hard to read
  docstrings. 

However, reStructuredText is not to blame here, as the dense, hard to read
docstrings are a consequence of the Sphinx docstring conventions. The Numpy
Style is valid rST and extracted docstrings could be used with standard
Docutils (rst2html, say) -- it works but you will loose some of the bells
and whistles like Sphinx-added cross-links.

__ http://www.sphinx-doc.org/en/stable/ext/napoleon.html

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

I see your point -- the restriction that term and classifiers in a
definition list need to be on one line.
(Note that similar restrictions exist for, e.g. section headings.)

We have to consider whether use cases that suffer from this restriction
are strong enough to merit a complication of the specification and code.
(This is not blanck rejection of any change to rST syntax. However, 
simpler alternatives may exist for the problematic use cases.)


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

In the given example, I agree with you and napoleon.

However, in case of long argument type list, falling back to the explicit
markup provided by the Sphinx docstring conventions may even be considered
as improving clarity. Compare ::

    Parameters
    ----------
    arg1 : a long list of argument types that does not fit on a line and\
           therfore must be wrapped
        Description of arg1
    arg2 : str
        Description of arg2

to ::

    Parameters
    ----------
    arg1
        :type:`a long list of argument types that does not fit on a line
	 and therfore must be wrapped`
	 
        Description of arg1
	
    arg2 : str
        Description of arg2

or a convention with nested definition lists::

    Parameters
    ----------
    arg1
        type:
	  a long list of argument types that does not fit on a line
	  and therfore must be wrapped
	 
        Description of arg1
	
    arg2 : str
        Description of arg2


As for the suggestions to extend the rST syntax, I think David is the
expert that can tell whether this fits into the overal picture and can be
implemented without too many complications.

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

Günter