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

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

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


David has privately replied to me (I assume this was a mistake of
reply-to-me vs. reply-to-mailing list -- apologizing in advance if this was
not the case) indicating cautious interest in the idea of
backslash-line-continuations.  Let's wait until he comments on the mailing
list.
I guess the same mechanism could be used for multi-line section headings,
etc.
Antony

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