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

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!

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

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

On Tue, Sep 26, 2017 at 5:28 AM, Robin Shannon <rj...@ro...> wrote:
> On 26 September 2017 at 06:45, David Goodger <go...@py...> wrote:
>>
>>
>> First, do you really need to implement a directive? You could just
>> embed the HTML in your reST source (``.. raw:: html``). It may be a
>> heck of a lot easier.
>
>
> Sage advice, but yes I do. Partly as a challenge to get my head around how
> classes work, and partly because it is a frequently requested feature in
> hovercraft (an html presentation generator).
>
>>
>> In your use case, do you want to allow multiple <track> elements
>> inside <video>? Multiple <source> elements? The HTML standard allows
>> multiples: videos in different formats, subtitles and captions in
>> different languages, etc. If the answer to either of these is "yes",
>> then you'll need something more robust.
>
>
> yes
>
>>
>> The only real *options* you'd have in this directive are "autoplay"
>> and "controls". And since they are simply flags (boolean attributes),
>> just include one to indicate "on" or exclude it to indicate "off";
>> don't use "true" and "false" values. See the "contents" directive
>> attribute "local" for an example.
>
>
> Thanks for pointing that out, that's a much better idea.
>
>>
>> The "track"-related data aren't options, they're content. If you have
>> a track, you must include certain attributes for it to make sense.
>> Then you have "required options", which is a contradiction in terms.
>> Bad smell, don't do that. And you can have multiple tracks, but it
>> doesn't generally make sense to repeat options. If you can standardize
>> the exact attributes you'll need (i.e. no variation), you can
>> implement these as a bullet list (one item per track) with positional
>> parameters (kind, language, source)::
>>
>>     * subtitles en foo.vtt
>
>
>
> Again, a much better idea.
> So, poking around in some of the other directives, it looks like the list
> items would be available to the directive as self.content and I would then
> split them by newlines. Or is there some other better way to get them
> already parsed as individual list items?

Do NOT split by newlines. Your directive lives inside a parser: use
the parser instead. You should do a recursive parse on the directive
content. See, for example, the list-table directive (class
docutils.parsers.rst.directives.tables.ListTable).

> Sorry, I appreciate that docutils
> is very well documented, but it is still quite confusing for a python
> neophyte.

Docutils is not comprehensively documented. A lot of the time the
answer will be, "Look at existing, similar examples," followed by,
"Use the Source, Luke!"

>> For example, allowing for multiple sources in the directive arguments,
>>     .. video:: foo.mp4 foo.webm foo.ogg
>
>
> Yep, that's how I've got it already. At least I had one good idea :) Is
> there some way of setting the optional_arguments parameter to unlimited or
> do I just set that to 10 safe in the knowledge that it would be a really
> strange use case that would need more than 11 different sources. It just
> seems slightly inelegant.

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.

> Thank you for your advice. It's very helpful.

You're welcome.

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

Re: [Docutils-users] Approach for resolving unknown references with pure docutils

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

On Sun, Sep 24, 2017 at 8:41 PM, Tony N <to...@gi...> wrote:
>
> On September 20, 2017 at 11:19:44 PM, David Goodger (go...@py...)
> wrote:
>
> On Wed, Sep 20, 2017 at 9:29 PM, Tony N <to...@gi...> wrote:
> > Docutils Users,
>
> This should be on the docutils-develop list.
>
> > Currently, sphinx has an infrastructure geared toward resolving unknown
> > references. I have not been able to find an approach for a custom
> reference
> > resolver mentioned before on the list.
> >
> > What would the best approach be for wiring in a callback to resolve
> missing
> > references with pure docutils?
>
> Not exactly sure what you're talking about. Examples go a long way.
>
> I'm guessing you're talking about resolving hyperlink references. (I
> don't like to guess; please don't make me.)
>
> So let’s say we have a role that isn't registered *and* is also
> an unknown reference, but I have the logic to figure out the role and
> resolve the hyperlink if I could catch the role + target. (So pretty much
> what you said, and what sphinx does, although they complicate it a lot)
>
> For instance:
>
> :class:`flask:flask.Request` and :class:`django:django.http.HttpRequest`
>
> In this instance, I would hope to be able to catch ‘class’,
> ‘flask:flask.Request’, and then I can handle resolving it into a reference.
>

What would do the catching?

Now I’d get this: <string>:4: (ERROR/3) Unknown interpreted text role
> "class"
>
> To be specific, here’s what Sphinx does (I neglected to cite example
> earlier since it adds a lot of overhead):
>
> - ReferenceResolver transformer  https://github.
> com/sphinx-doc/sphinx/blob/6765c54/sphinx/transforms/
> post_transforms/__init__.py#L63
>

"Transform", not "transformer". No Autobots or Decepticons allowed here; we
don't serve their kind.


> - Callback that resolves references: https://github.
> com/sphinx-doc/sphinx/blob/3f1f5bb/sphinx/ext/intersphinx.py#L270
>
> So to revise the question, it’s also two things:
>
> 1. Handle the role that’s unknown
>

Not supported in Docutils.


> (I guess the simplest solution is to write a pure-docutils class role?)
>

If you want a role to do some special processing, you have to implement it.
So, yes.


> I may end up having to port “domains” from sphinx to being a pure docutils
> extension at that rate.
>

No idea what that means.


> 2. Also handle resolving the reference. But note, the role plays a part in
> deducing the reference. Which I don’t expect would be a problem, that
> information would be there (right?)
>

The role name is passed to the role code, if that's what you're asking.

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

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

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

On 26 September 2017 at 06:45, David Goodger <go...@py...> wrote:

>
> First, do you really need to implement a directive? You could just
> embed the HTML in your reST source (``.. raw:: html``). It may be a
> heck of a lot easier.
>

Sage advice, but yes I do. Partly as a challenge to get my head around how
classes work, and partly because it is a frequently requested feature in
hovercraft (an html presentation generator).


> In your use case, do you want to allow multiple <track> elements
> inside <video>? Multiple <source> elements? The HTML standard allows
> multiples: videos in different formats, subtitles and captions in
> different languages, etc. If the answer to either of these is "yes",
> then you'll need something more robust.
>

yes


> The only real *options* you'd have in this directive are "autoplay"
> and "controls". And since they are simply flags (boolean attributes),
> just include one to indicate "on" or exclude it to indicate "off";
> don't use "true" and "false" values. See the "contents" directive
> attribute "local" for an example.
>

Thanks for pointing that out, that's a much better idea.


> The "track"-related data aren't options, they're content. If you have
> a track, you must include certain attributes for it to make sense.
> Then you have "required options", which is a contradiction in terms.
> Bad smell, don't do that. And you can have multiple tracks, but it
> doesn't generally make sense to repeat options. If you can standardize
> the exact attributes you'll need (i.e. no variation), you can
> implement these as a bullet list (one item per track) with positional
> parameters (kind, language, source)::
>
>     * subtitles en foo.vtt
>


Again, a much better idea.
So, poking around in some of the other directives, it looks like the list
items would be available to the directive as self.content and I would then
split them by newlines. Or is there some other better way to get them
already parsed as individual list items? Sorry, I appreciate that docutils
is very well documented, but it is still quite confusing for a python
neophyte.

For example, allowing for multiple sources in the directive arguments,
>     .. video:: foo.mp4 foo.webm foo.ogg


Yep, that's how I've got it already. At least I had one good idea :) Is
there some way of setting the optional_arguments parameter to unlimited or
do I just set that to 10 safe in the knowledge that it would be a really
strange use case that would need more than 11 different sources. It just
seems slightly inelegant.

Thank you for your advice. It's very helpful.

Peace,
Robin.

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

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

On Sun, Sep 24, 2017 at 5:39 PM, Robin Shannon <rj...@ro...> wrote:
> G'day,
>
> Firstly, thanks to everybody who has worked on ReST/docutils, you're
> awesome.
>
> I'm trying to create a custom directive for videos (my only output is html),
> and I would like to be able to include tracks (subtitle files) within the
> directive.
>
> For those unfamiliar with html5 video, the output looks something like this:
> <video autoplay>
> <source src="foo.ogg">
> <track kind="subtitles" src="foo.vtt" srclang="en">
> </video>
>
> What I'd like is a directive with nested field lists. eg:
> .. video:: sources
>     :autoplay: True
>     :track: :src: foo.vtt
>                :srclang: en
>                :kind: subtitles
>     :controls: false
>
> I saw nested lists like this somewhere in the sandbox (though now I can't
> find it again), but I think it was just a suggestion rather than an actually
> implemented directive. If this is possible, how would it work with
> option_spec in the directive definition? Alternatively is there a better way
> of solving this problem?

First, do you really need to implement a directive? You could just
embed the HTML in your reST source (``.. raw:: html``). It may be a
heck of a lot easier.

Next, do you really need the nesting? How about something like this::

 .. video:: sources
     :autoplay: True
     :src: foo.vtt
     :srclang: en
     :kind: subtitles
     :controls: false

The input does not have to match the output exactly, as long as it's
not ambiguous. If the three "nested" field names are unique, they can
simply be mapped to the required attributes and you don't need the
"track" field at all.

In general, try to avoid explicit boilerplate and complex data structures.

In your use case, do you want to allow multiple <track> elements
inside <video>? Multiple <source> elements? The HTML standard allows
multiples: videos in different formats, subtitles and captions in
different languages, etc. If the answer to either of these is "yes",
then you'll need something more robust.

The only real *options* you'd have in this directive are "autoplay"
and "controls". And since they are simply flags (boolean attributes),
just include one to indicate "on" or exclude it to indicate "off";
don't use "true" and "false" values. See the "contents" directive
attribute "local" for an example.

The "track"-related data aren't options, they're content. If you have
a track, you must include certain attributes for it to make sense.
Then you have "required options", which is a contradiction in terms.
Bad smell, don't do that. And you can have multiple tracks, but it
doesn't generally make sense to repeat options. If you can standardize
the exact attributes you'll need (i.e. no variation), you can
implement these as a bullet list (one item per track) with positional
parameters (kind, language, source)::

    * subtitles en foo.vtt

And even if there is some variation, you can add some punctuation to
make things clear, something like::

    * subtitles en foo.vtt "label text here" **default**

Or even::

    * **subtitles** en foo.vtt "label text here"

The emphasized "**subtitles**" could indicate "default".

For example, allowing for multiple sources in the directive arguments,

    .. video:: foo.mp4 foo.webm foo.ogg
       :autoplay:
       :controls:

       * subtitles en foo.vtt
       * subtitles fr foo-fr.vtt

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

Re: [Docutils-users] Approach for resolving unknown references with pure docutils

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

On September 20, 2017 at 11:19:44 PM, David Goodger (go...@py...)
wrote:

On Wed, Sep 20, 2017 at 9:29 PM, Tony N <to...@gi...> wrote:
> Docutils Users,

This should be on the docutils-develop list.

> Currently, sphinx has an infrastructure geared toward resolving unknown
> references. I have not been able to find an approach for a custom
reference
> resolver mentioned before on the list.
>
> What would the best approach be for wiring in a callback to resolve
missing
> references with pure docutils?

Not exactly sure what you're talking about. Examples go a long way.

I'm guessing you're talking about resolving hyperlink references. (I
don't like to guess; please don't make me.)

So let’s say we have a role that isn't registered *and* is also an unknown
reference, but I have the logic to figure out the role and resolve the
hyperlink if I could catch the role + target. (So pretty much what you
said, and what sphinx does, although they complicate it a lot)

For instance:

:class:`flask:flask.Request` and :class:`django:django.http.HttpRequest`

In this instance, I would hope to be able to catch ‘class’,
‘flask:flask.Request’, and then I can handle resolving it into a reference.

Now I’d get this: <string>:4: (ERROR/3) Unknown interpreted text role
"class"

To be specific, here’s what Sphinx does (I neglected to cite example
earlier since it adds a lot of overhead):

- ReferenceResolver transformer
https://github.com/sphinx-doc/sphinx/blob/6765c54/sphinx/transforms/post_transforms/__init__.py#L63

- Callback that resolves references:
https://github.com/sphinx-doc/sphinx/blob/3f1f5bb/sphinx/ext/intersphinx.py#L270

So to revise the question, it’s also two things:

1. Handle the role that’s unknown (I guess the simplest solution is to
write a pure-docutils class role?) I may end up having to port “domains”
from sphinx to being a pure docutils extension at that rate.

2. Also handle resolving the reference. But note, the role plays a part in
deducing the reference. Which I don’t expect would be a problem, that
information would be there (right?)



> If it’s a transformer, when and where would
> would it be added/applied?

Transforms, not "transformers". Docutils has one Transformer,
docutils.transforms.Transformer, which stores and applies Transforms.

Understood.



> (It appears the other reference resolvers in
> docutils are in the Reader).

The hook you're looking for is here:
docutils/__init__.py::TransformSpec.unknown_reference_resolvers

For an example, see sandbox/mmgilbe/rst.py, the original
MoinMoin/Docutils interface code.

That helps significantly. I am going to give that a try. Never noticed that
before!



> P.S. An aside, parsers/rst/states.py has an unused
> UnknownInterpretedRoleError exception.

OK... Do you have a point, other than this showing up in linter output?

No, just found it. Wasn’t a linter, saw it, grep’d and saw it wasn’t
implemented, thought it’d be related to the question and wanted to mention.
Was a Chesterton’s fence to me.



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

[Docutils-users] nested field lists in custom directives

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

G'day,

Firstly, thanks to everybody who has worked on ReST/docutils, you're
awesome.

I'm trying to create a custom directive for videos (my only output is
html), and I would like to be able to include tracks (subtitle files)
within the directive.

For those unfamiliar with html5 video, the output looks something like this:
<video autoplay>
<source src="foo.ogg">
<track kind="subtitles" src="foo.vtt" srclang="en">
</video>

What I'd like is a directive with nested field lists. eg:
.. video:: sources
    :autoplay: True
    :track: :src: foo.vtt
               :srclang: en
               :kind: subtitles
    :controls: false

I saw nested lists like this somewhere in the sandbox (though now I can't
find it again), but I think it was just a suggestion rather than an
actually implemented directive. If this is possible, how would it work with
option_spec in the directive definition? Alternatively is there a better
way of solving this problem?

Thank you,
Robin.

Re: [Docutils-users] What classes and ids generates rst2html5?

[Leonhard K. <leo...@mo...>]

I totally forgot:

Thank you! :D

On Sat, 16 Sep 2017 18:31:22 +0000 (UTC)
Guenter Milde via Docutils-users <doc...@li...> wrote:

> On 2017-09-16, Leonhard Küper wrote:
> > Hello.
> 
> 
> > I want to generate html from restructuered text and I want to style it.
> > What selectors are generated? 
> 
> There is no dedicated documentation. You could look in the sources
> (modules _html_base.py and html5/__init__.py in docutils/writers/).
> The simplest way is to just try it out.
> 
> > Are there some tips what the generated
> > html could look like and how to style proper?
> 
> Have a look at the examples in tests/functional/expected.
> There you can also compare html4css1 and html5 output.
> 
> The CSS style files in docutils/writers/html5_polyglott/ are also good
> examples and comprehensive comments.
> 
> Günter
> 
> 
> 
> ------------------------------------------------------------------------------
> 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] Approach for resolving unknown references with pure docutils

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

On Wed, Sep 20, 2017 at 9:29 PM, Tony N <to...@gi...> wrote:
> Docutils Users,

This should be on the docutils-develop list.

> Currently, sphinx has an infrastructure geared toward resolving unknown
> references. I have not been able to find an approach for a custom reference
> resolver mentioned before on the list.
>
> What would the best approach be for wiring in a callback to resolve missing
> references with pure docutils?

Not exactly sure what you're talking about. Examples go a long way.

I'm guessing you're talking about resolving hyperlink references. (I
don't like to guess; please don't make me.)

> If it’s a transformer, when and where would
> would it be added/applied?

Transforms, not "transformers". Docutils has one Transformer,
docutils.transforms.Transformer, which stores and applies Transforms.

> (It appears the other reference resolvers in
> docutils are in the Reader).

The hook you're looking for is here:
docutils/__init__.py::TransformSpec.unknown_reference_resolvers

For an example, see sandbox/mmgilbe/rst.py, the original
MoinMoin/Docutils interface code.

> P.S.  An aside, parsers/rst/states.py has an unused
> UnknownInterpretedRoleError exception.

OK... Do you have a point, other than this showing up in linter output?

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

[Docutils-users] Approach for resolving unknown references with pure docutils

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

Docutils Users,

Currently, sphinx has an infrastructure geared toward resolving unknown
references. I have not been able to find an approach for a custom reference
resolver mentioned before on the list.

What would the best approach be for wiring in a callback to resolve missing
references with pure docutils? If it’s a transformer, when and where would
would it be added/applied? (It appears the other reference resolvers in
docutils are in the Reader).

Tony

P.S.  An aside, parsers/rst/states.py has an
unused UnknownInterpretedRoleError exception.

Re: [Docutils-users] What classes and ids generates rst2html5?

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

On 2017-09-16, Leonhard Küper wrote:
> Hello.


> I want to generate html from restructuered text and I want to style it.
> What selectors are generated? 

There is no dedicated documentation. You could look in the sources
(modules _html_base.py and html5/__init__.py in docutils/writers/).
The simplest way is to just try it out.

> Are there some tips what the generated
> html could look like and how to style proper?

Have a look at the examples in tests/functional/expected.
There you can also compare html4css1 and html5 output.

The CSS style files in docutils/writers/html5_polyglott/ are also good
examples and comprehensive comments.

Günter

[Docutils-users] What classes and ids generates rst2html5?

[Leonhard K. <leo...@mo...>]

Hello.


I want to generate html from restructuered text and I want to style it. What selectors are generated? Are there some tips what the generated html could look like and how to style proper?


Sincerely
Leonhard

Re: [Docutils-users] Unicode issue in rst2html5 utility

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

On 2017-09-15, Michal Dabski wrote:

Dear Michal,

thank you for the report.

> I'm not subscribed to the mailing list, just wanted to raise an issue I
> found while making messages using Django's makemessage command with
> docutils installed.

> I'm getting the following message:

> $ python manage.py makemessages
> CommandError: errors happened while running xgettext on rst2html5.py
> xgettext: ./bin/rst2html5.py:2: Unknown encoding "utf8". Proceeding with
> ASCII instead.
> xgettext: Non-ASCII comment at or before ./bin/rst2html5.py:3.
> Please specify the source encoding through --from-code or through a comment
> as specified in http://www.python.org/peps/pep-0263.html.

> It looks like "utf8" is not a valid encoding, surely it should be "utf-8"?

According to the Python documentation, both "utf-8" and "utf8" are valid
aliases for the "utf_8" codec and the file is processed without problem by
Python.

OTOH, all other source files use the utf-8 alias in the source encoding
comment, so we will change this for inner consistency.

Thanks,

Günter

[Docutils-users] Unicode issue in rst2html5 utility

[Michal D. <mi...@me...>]

Hi,

I'm not subscribed to the mailing list, just wanted to raise an issue I
found while making messages using Django's makemessage command with
docutils installed.

I'm getting the following message:

$ python manage.py makemessages
CommandError: errors happened while running xgettext on rst2html5.py
xgettext: ./bin/rst2html5.py:2: Unknown encoding "utf8". Proceeding with
ASCII instead.
xgettext: Non-ASCII comment at or before ./bin/rst2html5.py:3.
Please specify the source encoding through --from-code or through a comment
as specified in http://www.python.org/peps/pep-0263.html.

It looks like "utf8" is not a valid encoding, surely it should be "utf-8"?

-- 
Michal Dabski
Chief Technical Officer
MEG Support Tools

Re: [Docutils-users] rst2html5.py on mac doesn't support --embed-stylesheet and other options?

[engelbert g. <eng...@gm...>]

On 25 August 2017 at 10:23, Lee Griffiths <lgr...@mi...>
wrote:

> He simply did `pip install docutils`.
>

I just tried this here. with a lot pip uninstall and rm, because i have
plenty of docutils in 3.6 and 2.7 and ... but in the end rst2html5.py no
longer worked

i did ::

  pip install docutils

the installation is in ::

  /Library/Frameworks/Python.framework/Versions/2.7/bin/rst2html5.py

and ::


/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages


::

  > rst2html5.py --version
  rst2html5.py (Docutils 0.14, Python 2.7.10, on darwin)

  > rst2html5.py --help
  Usage
  =====
    rst2html5.py [options] [<source> [<destination>]]

  HTML-Specific Options
  ---------------------
  --template=<file>       Specify the template file (UTF-8 encoded).
Default is

"/Library/Frameworks/Python.framework/Versions/2.7/lib

/python2.7/site-packages/docutils/writers/html5_polygl
                        ot/template.txt".
  --stylesheet=<URL[,URL,...]>
                        Comma separated list of stylesheet URLs. Overrides
                        previous --stylesheet and --stylesheet-path
settings.
  --stylesheet-path=<file[,file,...]>
                        Comma separated list of stylesheet paths. Relative
                        paths are expanded if a matching file is found in
the
                        --stylesheet-dirs. With --link-stylesheet, the path
is
                        rewritten relative to the output HTML file. Default:
                        "minimal.css,plain.css"
  --embed-stylesheet      Embed the stylesheet(s) in the output HTML file.
The
                        stylesheet files must be accessible during
processing.
                        This is the default.
  --link-stylesheet       Link to the stylesheet(s) in the output HTML file.
                        Default: embed stylesheets.
  --stylesheet-dirs=<dir[,dir,...]>
                        Comma-separated list of directories where
stylesheets
                        are found. Used by --stylesheet-path when expanding
                        relative path arguments. Default: "['.',
'/Library/Fra
                        meworks/Python.framework/Versions/2.7/lib/python2.7
                        /site-packages/docutils/writers/html5_polyglot']"
  --initial-he


> Can you think of anything that would go "wrong" here that would somehow
> have his version of rst2html5.py being nothing like ours?
>

and in his version --help does not show the same stylesheet options
then there must be another writer directory somewhere ?


>
> On 24 August 2017 at 16:50, engelbert gruber <eng...@gm...>
> wrote:
>
>> strange
>>
>>
>> rst2html5.py (Docutils 0.14, Python 2.7.10, on darwin)
>>
>> --help
>>
>> HTML-Specific Options
>> ---------------------
>> --template=<file>       Specify the template file (UTF-8 encoded).
>> Default is
>>                         "/Library/Frameworks/Python.fr
>> amework/Versions/2.7/lib
>>                         /python2.7/site-packages/docut
>> ils/writers/html5_polygl
>>                         ot/template.txt".
>> --stylesheet=<URL[,URL,...]>
>>                         Comma separated list of stylesheet URLs. Overrides
>>                         previous --stylesheet and --stylesheet-path
>> settings.
>> --stylesheet-path=<file[,file,...]>
>>                         Comma separated list of stylesheet paths. Relative
>>                         paths are expanded if a matching file is found in
>> the
>>                         --stylesheet-dirs. With --link-stylesheet, the
>> path is
>>                         rewritten relative to the output HTML file.
>> Default:
>>                         "minimal.css,plain.css"
>> --embed-stylesheet      Embed the stylesheet(s) in the output HTML file.
>> The
>>                         stylesheet files must be accessible during
>> processing.
>>                         This is the default.
>> --link-stylesheet       Link to the stylesheet(s) in the output HTML file.
>>                         Default: embed stylesheets.
>> --stylesheet-dirs=<dir[,dir,...]>
>>                         Comma-separated list of directories where
>> stylesheets
>>                         are found. Used by --stylesheet-path when
>> expanding
>>                         relative path arguments. Default: "['.',
>> '/Library/Fra
>>                         meworks/Python.framework/Versi
>> ons/2.7/lib/python2.7
>>                         /site-packages/docutils/writers/html5_polyglot']"
>>
>>
>>
>> On 24 August 2017 at 10:57, Lee Griffiths <lgr...@mi...>
>> wrote:
>>
>>>
>>> Hi
>>>
>>> (Note: I'm not subscribed to the mailing list)
>>>
>>> A colleague is having trouble using a script that I wrote which utilises
>>> `rst2html5.py` from the docutils package. The problem is that his version
>>> of rst2html5.py doesn't contain the `--embed-stylesheet` or
>>> `--stylesheet-path` options, which seems really strange to me.
>>>
>>> His version of rst2html4.py and rst2html.py *do* contain those options,
>>> so I've simply changed the script to use those instead.
>>>
>>> But I would expected all of these tools to have (almost) identical input
>>> parameters and simply create different html files. I wouldn't expect a
>>> document generation tool written in python to have platform specific
>>> behaviour.
>>>
>>> Is this expectation correct? What causes this difference between
>>> platforms? Is this unexpected to anyone else?
>>>
>>>
>>> Thanks,
>>> Lee
>>>
>>>
>>> I've attached the --help output for rst2html.py and rst2html5.py for
>>> both platforms. Note that for my windows machine I've put the explicit path
>>> to the script rather than just executing `rst2html.py` as my PATH points to
>>> the python3 one, and I wanted to keep the differences to a minimum.
>>>
>>> mac:
>>>
>>> $ rst2html.py --version
>>>
>>> rst2html.py (Docutils 0.14, Python 2.7.12, on darwin)
>>>
>>>
>>>
>>> $ rst2html5.py --version
>>>
>>> rst2html5.py (Docutils 0.14, Python 2.7.12, on darwin)
>>>
>>>
>>>
>>> $ which rst2html5.py
>>>
>>> /Library/Frameworks/Python.framework/Versions/2.7/bin/rst2html5.py
>>>
>>>
>>>
>>> $ which rst2html.py
>>>
>>> /Library/Frameworks/Python.framework/Versions/2.7/bin/rst2html.py
>>>
>>>
>>>
>>> win:
>>>
>>> $ /c/dev/env/python/Python27/Scripts/rst2html5.py --version
>>> rst2html5.py (Docutils 0.14, Python 2.7.12, on win32)
>>>
>>> $ /c/dev/env/python/Python27/Scripts/rst2html.py --version
>>> rst2html.py (Docutils 0.14, Python 2.7.12, on win32)
>>>
>>>
>>>
>>>
>>>
>>>
>>>
>>> ------------------------------------------------------------
>>> ------------------
>>> 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.
>>>
>>>
>>
>