Re: Multi-line classifiers in definition lists

Hi,
Sorry re-raising an old thread, but I had a quick revisit at this again...
As a reminder, this was about adding backslash-escaped line continuations,
so that one could write

term : info more info \

       and more info

    the definition


the idea being that numpydoc docstrings (by far the most widely used
docstring convention in the scientific python ecosystem) would benefit from
it.
As it turns out the patch to achieve this is relatively simple:

diff --git i/docutils/docutils/statemachine.py
w/docutils/docutils/statemachine.py
index ec5351887..70aa9baea 100644
--- i/docutils/docutils/statemachine.py
+++ w/docutils/docutils/statemachine.py
@@ -311,6 +311,13 @@ class StateMachine(object):
            except IndexError:
                self.line = None
                raise EOFError
+            while self.line.endswith("\\"):
+                try:
+                    self.line_offset += 1
+                    self.line +=
self.input_lines[self.line_offset].lstrip()
+                except IndexError:
+                    self.line = None
+                    raise EOFError
            return self.line
        finally:
            self.notify_observers()


i.e. joining the backslash-escaped lines relatively early in the process.
Please let me know the best way to proceed forward.

Cheers,
Antony

On Mon, Oct 9, 2017 at 5:21 AM David Goodger <[email protected]> wrote:

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