docutils-users — General discussions, questions, help requests.

Re: [Docutils-users] ISBN URL?

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

On 2017-12-22, Matěj Cepl wrote:
> On 2017-05-11, 21:30 GMT, Guenter Milde wrote:
>> Unfortunately, this does not help in praxi, as

>>   Your browser would have to have a "resolver" installed for ISBN numbers
>>   that would find a URL for the resource. As far as I know, no browsers
>>   have taken a stab at implementing resolvers as called for by the RFC.
>>   –- Stephen Ostermiller Feb 24 at 8:57 

> So, to translate your post into English: there is nothing to 
> help you. Right?

To rephrase my answer:

  While Docutils already supports isbn URLs in the rst source (e.g. `The
  Four Loves <urn:isbn:0156329301>`__), this will most likely not work
  with current browsers which lack support for RFC 2187 and just return an
  error when told to go to "urn:isbn:0156329301".
  
Taking in account the current state of browser (non)support, I can imagine
a transform mapping ISBN URLs to a configurable HTML URL like ::

  'https://en.wikipedia.org/wiki/Special:BookSources?isbn=%s' % isbn_no
  
Patches welcome.

Günter

Re: [Docutils-users] unintentional print?

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

Dear Alan,

thank you for reporting. This is fixed now in the SVN repo.

On 2018-01-03, Alan Isaac wrote:
> I'm guessing that 2to3 conversion is used to support Python 3,

Yes, this is still required. (For fast install, we provide pre-converted
"wheels" on pypi.)

> but somehow I recently managed to choke on:

> File "docutils\utils\math\tex2mathml_extern.py", line 130
>      print err

> Although this could be "fixed" with parentheses, but
> I'm guessing the very existence of this line is an oversight.

> Cheers,
> Alan Isaac

> PS While looking, I noticed old style exception syntax in use.
> I assume this is intentional (i.e., let the converter handle it)
> and that you know Python 2's

>      except IOError, err:

> could be written without any need for 2to3 conversion as

>      except IOError:
>          err = sys.exc_info()[1]

Actually, since we dropped support for Python < 2.6 we can now also use the
simpler

   except IOError as err:
   
and other python-3-save constructs.

Günter   

[Docutils-users] unintentional print?

[Alan I. <ala...@gm...>]

I'm guessing that 2to3 conversion is used to support Python 3,
but somehow I recently managed to choke on:

File "docutils\utils\math\tex2mathml_extern.py", line 130
     print err

Although this could be "fixed" with parentheses, but
I'm guessing the very existence of this line is an oversight.

Cheers,
Alan Isaac

PS While looking, I noticed old style exception syntax in use.
I assume this is intentional (i.e., let the converter handle it)
and that you know Python 2's

     except IOError, err:

could be written without any need for 2to3 conversion as

     except IOError:
         err = sys.exc_info()[1]

Re: [Docutils-users] ISBN URL?

[Matěj C. <mc...@ce...>]

On 2017-05-11, 21:30 GMT, Guenter Milde wrote:
> Unfortunately, this does not help in praxi, as
>         
>   Your browser would have to have a "resolver" installed for ISBN numbers
>   that would find a URL for the resource. As far as I know, no browsers
>   have taken a stab at implementing resolvers as called for by the RFC.
>   –- Stephen Ostermiller Feb 24 at 8:57 

So, to translate your post into English: there is nothing to 
help you. Right?

Best,

Matěj
-- 
http://matej.ceplovi.cz/blog/, Jabber: mcepl<at>ceplovi.cz
GPG Finger: 3C76 A027 CA45 AD70 98B5  BC1D 7920 5802 880B C9D8
 
The truth is a beautiful and terrible thing, and should therefore
be treated with caution.
  -- Albus Dumbledore

Re: [Docutils-users] Using attributes in the "class" directive

[David G. <go...@py...>]

On Thu, Dec 21, 2017 at 7:41 AM,
<doc...@ay...> wrote:
> According to the spec, the "class" attribute accepts class names and also
> attribute values as directive arguments [1].
>
> [1] http://docutils.sourceforge.net/docs/ref/rst/directives.html#class

You misunderstand the spec. The class names *become* the "classes"
attribute of its contents or the immediately-following element.

> The examples for the "class" attribute only include class names but not
> attribute values.

This reST::

    .. class:: special

    This is a "special" paragraph.

becomes this doctree fragment (XML)::

    <paragraph classes="special">This is a "special" paragraph.</paragraph>

> Is it really possible to assign attributes to a class name
> by using the "class" directive?

No, that doesn't make sense.

David Goodger
<http://python.net/~goodger>

[Docutils-users] Using attributes in the "class" directive

[<doc...@ay...>]

According to the spec, the "class" attribute accepts class names and 
also attribute values as directive arguments [1].

The examples for the "class" attribute only include class names but not 
attribute values. Is it really possible to assign attributes to a class 
name by using the "class" directive?

Gökçe

[1] http://docutils.sourceforge.net/docs/ref/rst/directives.html#class

Re: [Docutils-users] HTML <div style="width:40%">

[Gökçe A. <doc...@ay...>]

Thank you Günter and David. It makes sense that rST does not support 
direct styling — this is what stylesheets are for.

I'll explain the background of my question: Pandoc can generate beamer 
slides. For slides, it is also possible to generate columns and specify 
the width in Pandoc's Markdown as follows [1]:

:::::::::::::: {.columns}
::: {.column width="40%"}
contents...
:::
::: {.column width="60%"}
contents...
:::
::::::::::::::

This block generates the following HTML:

<div class="columns">
   <div class="column" style="width:40%;">
     <p>contents…</p>
   </div>
   <div class="column" style="width:60%;">
     <p>contents…</p>
   </div>
</div>

I wanted to do the same with rST. As you have suggested I tried with 
container:: and class:: directives, which could generate a beamer slide 
with columns in pandoc:

.. class:: columns

    .. class:: column

       - first

    .. class:: column

       - second

Note that also container:: directive can be used in the preceding 
example. I could not figure out how to create the style attribute when 
using rST as input in Pandoc. Although Pandoc accepts CSS for 
HTML/CSS-to-pdf output, it does not support CSS input along with rST I 
suppose. I will create a request for that.

Gökçe

[1] https://pandoc.org/MANUAL.html#columns


Am 2017-11-22 22:43, schrieb David Goodger:
> Yes, it's possible. But not recommended. Directly, the only way is
> with the "raw" directive:
> http://docutils.sourceforge.net/docs/ref/rst/directives.html#raw-data-pass-through
> But that is a last resort only. I do NOT recommend it.
> 
> What you're talking about is styling your HTML. You should use
> stylesheets for that:
> http://docutils.sourceforge.net/docs/howto/html-stylesheets.html
> 
> Use the "class" directive (or "class" option on an existing directive)
> to assign custom classes if necessary:
> http://docutils.sourceforge.net/docs/ref/rst/directives.html#class
> 
> What, in your document, are you trying to style?
> 
> David Goodger
> <http://python.net/~goodger>
> 
> 
> On Wed, Nov 22, 2017 at 8:55 AM, Gökçe Aydos
> <doc...@ay...> wrote:
>> Is it possible to generate HTML output as follows?
>> 
>> <div style="width:40%">
>> contents...
>> </div>
>> 
>> Regards, Gökçe
>> 
>> ------------------------------------------------------------------------------
>> 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
>> Doc...@li...
>> https://lists.sourceforge.net/lists/listinfo/docutils-users
>> 
>> Please use "Reply All" to reply to the list.

Re: [Docutils-users] HTML <div style="width:40%">

[David G. <go...@py...>]

Yes, it's possible. But not recommended. Directly, the only way is
with the "raw" directive:
http://docutils.sourceforge.net/docs/ref/rst/directives.html#raw-data-pass-through
But that is a last resort only. I do NOT recommend it.

What you're talking about is styling your HTML. You should use
stylesheets for that:
http://docutils.sourceforge.net/docs/howto/html-stylesheets.html

Use the "class" directive (or "class" option on an existing directive)
to assign custom classes if necessary:
http://docutils.sourceforge.net/docs/ref/rst/directives.html#class

What, in your document, are you trying to style?

David Goodger
<http://python.net/~goodger>


On Wed, Nov 22, 2017 at 8:55 AM, Gökçe Aydos
<doc...@ay...> wrote:
> Is it possible to generate HTML output as follows?
>
> <div style="width:40%">
> contents...
> </div>
>
> Regards, Gökçe
>
> ------------------------------------------------------------------------------
> 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
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
>
> Please use "Reply All" to reply to the list.

Re: [Docutils-users] HTML <div style="width:40%">

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

On 2017-11-22, Gökçe Aydos wrote:
> Is it possible to generate HTML output as follows?

><div style="width:40%">
> contents...
></div>

This can be done with raw HTML only.

OTOH, you could use the rST equivalent to a <div> and give it a class argument
that can be styled via a custom CSS stylesheet::

  .. container:: custom

     This paragraph might be rendered in a custom way.
     
becomes::

 <div class="custom docutils container">
 <p>This paragraph might be rendered in a custom way.</p>
 </div>
 
Günter    

[Docutils-users] HTML <div style="width:40%">

[Gökçe A. <doc...@ay...>]

Is it possible to generate HTML output as follows?

<div style="width:40%">
contents...
</div>

Regards, Gökçe

Re: [Docutils-users] Test suite failure

[David G. <go...@py...>]

Please provide some details:
http://docutils.sourceforge.net/BUGS.html#how-to-report-a-bug

David Goodger
<http://python.net/~goodger>


On Tue, Nov 21, 2017 at 12:00 AM, Gabrielle Lundie
<gab...@gm...> wrote:
>
> ------------------------------------------------------------------------------
> 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
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
>
> Please use "Reply All" to reply to the list.
>

[Docutils-users] Test suite failure

[Gabrielle L. <gab...@gm...>]

Re: [Docutils-users] camelCase directives not working

[David G. <go...@py...>]

This is a feature, or at least part of the spec. According to
http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#directives:

"Directive types are case-insensitive single
words (alphanumerics plus isolated internal hyphens, underscores,
plus signs, colons, and periods; no whitespace)."

The directive "type" is its name. What "case-insensitive" means here
is that in documents, you can refer to your directive as
"eventListner" or "EventListner" or "eventlistner" or "eVeNtLiStNeR"
or whatever. This is achieved by normalizing the directive name in the
document to "eventlistner", all lowercase. To match, the directive
name must also be all-lowercase at registration time; no normalization
happens then. Registering your directive as "eventListner", with mixed
case, made it impossible to match the name to its use in documents.

Directive names are effectively case-sensitive at registration time,
and must be lowercase. We could add name normalization code to ensure
that this is always true, or a check to warn if it isn't true. As this
is the first time I've seen this, I don't know if it's worth the
effort, small as it may be. I wouldn't object to such a change.

David Goodger
<http://python.net/~goodger>


On Sun, Oct 22, 2017 at 6:33 AM, Robin Shannon <rj...@ro...> wrote:
>
> I created a custom directive called 'eventListner'. After registering it and
> trying out a test reST document docutils told me that this was an unknown
> directive. Much confusion later, I finally figured out that if I renamed the
> directive to 'eventlistner' everything worked fine. Is this a feature or a
> bug? I looked through the list archive but couldn't find anything obvious
> about this.
>
> I admit that camelCase as a directive name is probably generally not a good
> idea, but since this is a shortcut for the javascript function
> 'eventListner' it seemed appropriate.
>
> Cheers,
> Robin.
>
>
> ------------------------------------------------------------------------------
> 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
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
>
> Please use "Reply All" to reply to the list.
>

[Docutils-users] camelCase directives not working

[Robin S. <rj...@ro...>]

I created a custom directive called 'eventListner'. After registering it
and trying out a test reST document docutils told me that this was an
unknown directive. Much confusion later, I finally figured out that if I
renamed the directive to 'eventlistner' everything worked fine. Is this a
feature or a bug? I looked through the list archive but couldn't find
anything obvious about this.

I admit that camelCase as a directive name is probably generally not a good
idea, but since this is a shortcut for the javascript function
'eventListner' it seemed appropriate.

Cheers,
Robin.

Re: [Docutils-users] Remove everything below nodes.title/nodes.subtitle from doctree?

[David G. <go...@py...>]

On Fri, Oct 13, 2017 at 11:11 AM, Tony N <to...@gi...> wrote:
> This was actually straight forward for me, see an example on a blog post
> here: http://homework.nwsnet.de/releases/af95/
>
> However, even though I’m removing the title, I’m still intending on storing
> reStructuredText.
>
> I forget there’s no reStructuredText Writer for docutils (one could only
> wish). So I ended up using a regex to chop the title portion out.

The Element.line, .source, and .rawsource attributes may be useful.

David Goodger
<http://python.net/~goodger>

> On October 12, 2017 at 2:54:59 PM, Tony N (to...@gi...) wrote:
>
> Since I am already able to read the title/subtitle from the doctree, now I
> want to be able to remove the title and subtitle from a doctree:
>
> What would be the canonical way of doing that?
>
> - Removing the nodes.title and nodes.subtitle from the doctree (how can that
> be done? Is there any examples to how that works?)
> - Removing all nodes *after* nodes.title and nodes.subtitle (any examples
> for something like that?)
>

Re: [Docutils-users] Remove everything below nodes.title/nodes.subtitle from doctree?

[David G. <go...@py...>]

On Thu, Oct 12, 2017 at 2:54 PM, Tony N <to...@gi...> wrote:
> Since I am already able to read the title/subtitle from the doctree, now I
> want to be able to remove the title and subtitle from a doctree:
>
> What would be the canonical way of doing that?

Docutils doctree elements wrap the sequence interface (pass-through to
Element.children). So use the same operations you would on a list.

> - Removing the nodes.title and nodes.subtitle from the doctree (how can that
> be done? Is there any examples to how that works?)

Assume doctree[0] is the title element (use, e.g. ``index =
Element.first_child_matching_class(nodes.title)``). ``del doctree[0]``
deletes the title.

> - Removing all nodes *after* nodes.title and nodes.subtitle (any examples
> for something like that?)

Assume doctree[1] is the subtitle element. ``del doctree[2:]`` does
what you want.

DG

Re: [Docutils-users] Remove everything below nodes.title/nodes.subtitle from doctree?

[Tony N <to...@gi...>]

This was actually straight forward for me, see an example on a blog post
here: http://homework.nwsnet.de/releases/af95/

However, even though I’m removing the title, I’m still intending on
*storing* reStructuredText.

I forget there’s no reStructuredText *Writer* for docutils (one could only
wish). So I ended up using a regex to chop the title portion out.


On October 12, 2017 at 2:54:59 PM, Tony N (to...@gi...) wrote:

Since I am already able to read the title/subtitle from the doctree, now I
want to be able to *remove* the title and subtitle from a doctree:

What would be the canonical way of doing that?

- Removing the nodes.title and nodes.subtitle from the doctree (how can
that be done? Is there any examples to how that works?)
- Removing all nodes *after* nodes.title and nodes.subtitle (any examples
for something like that?)

Re: [Docutils-users] nested field lists in custom directives

[Robin S. <rj...@ro...>]

To time travellers from the future (searching the list-archive):

This is actually really simple, when you figure out how it all works. All
you need to do to parse the content of a directive is the following:

node = nodes.Element()
self.state.nested_parse(self.content, self.content_offset, node)

First we create a node of class nodes.Element(). This node is not actually
part of the document tree! It is just a dummy container for us to put our
content while we work with it. Next we call the state.nested_parse method.
This method is inherited by all directives. It takes the content given to
the directive (that is everything after ".. driective::" that is indented
but isn't part of the options field list) and parses it and places the
output into the dummy container we just created (node). Now to access the
content we can access it as if it were a nested list.

So in my case node looked like this:
[Element[bullet_list[list_item[paragraph[Text]]]]].
To access the bullet_list node I just use node[0]. To access an attribute
of the bullet_list node I use node[0]['key']. Calling print(node) will show
you what your particular node looks like.

Maybe all that is really obvious, but it took me several days of fruitless
pain trying to understand states.py and statemachine.py, before I figured
it out.

For a more thorough walk thru of parsing the content of custom directives
see
https://github.com/vorpalvorpal/hovercraft/blob/master/hovercraft/local_directives/example.__init__.py


> optional_arguments could have been defined as "-1 is equivalent to
> infinity" (or some other sentinel value), but it wasn't. In cases like
> this, when you want to have an unlimited number, the standard idiom is
> to use sys.maxint, a very large number that is close enough to
> infinity for our purposes.
>


To time travellers from the future: python3 replaced sys.maxint with
sys.maxsize.

To David:
Thanks for your pointers. It made something that would have been impossible
for me, possible.

Cheers,
Robin.

[Docutils-users] Remove everything below nodes.title/nodes.subtitle from doctree?

[Tony N <to...@gi...>]

Since I am already able to read the title/subtitle from the doctree, now I
want to be able to *remove* the title and subtitle from a doctree:

What would be the canonical way of doing that?

- Removing the nodes.title and nodes.subtitle from the doctree (how can
that be done? Is there any examples to how that works?)
- Removing all nodes *after* nodes.title and nodes.subtitle (any examples
for something like that?)

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

[David G. <go...@py...>]

Oops, I meant to reply-all:

On Oct 7, 2017 10:48 PM, "David Goodger" <dgo...@gm...> 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" <ant...@be...> 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_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!

------------------------------------------------------------
------------------
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
Doc...@li...
https://lists.sourceforge.net/lists/listinfo/docutils-users

Please use "Reply All" to reply to the list.

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

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

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

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

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

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

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

[Antony L. <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!