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

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

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

[Lee G. <lgr...@mi...>]

He simply did `pip install docutils`.

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

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.
> 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']"
>
>
>
> 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.
>>
>>
>

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

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

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.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']"



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

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

[Lee G. <lgr...@mi...>]

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)

[Docutils-users] Introducing devel.tech, a docutils-powered website

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

Greetings docutils users,

I have recently created a website backed by docutils.  It’s called
https://devel.tech.

-
https://devel.tech/tips/n/sNZwQvNh/django-compressor-vs-django-webpack-loader/
(docutils, with Günter’s html5_polyglot Writer)
- https://devel.tech/site/updates (docutils)
- https://devel.tech/features/django-vs-flask/ (sphinx w/ WebSupport, but I
had to fork it
https://github.com/develtech/sphinxcontrib-websupport/tree/lean)

Docutils provides extensibility, customizability, and great access via
python. The site makes full use of the new html5_polyglot Writer as well as
various other database-backed roles and writer transformations.

My hope is to port sphinx features to work with pure docutils and open
source them as extensions. This way more people can leverage the power of
pure docutils without pulling in an additional framework.

About reStructuredText and why it was picked over markdown: the language is
consistent, similar enough to markdown, and allows for flexibility via
roles and directives. It was the most powerful, yet nimblest of the two; a
great fit for software developers.

Best,
Tony

[Docutils-users] Released 0.14

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

RELEASE-NOTES

nothing changed from rc2, except some release documentation and
clarification

* docutils/docs/ref/docutils.dtd:

  - Enable validation of Docutils XML documents against the DTD:

* docutils/parsers/rst/:

  - Added functionality: escaped whitespace in URI contexts.
  - Consistent handling of all whitespace characters in inline markup
    recognition. (May break documents that relied on some whitespace
    characters (NBSP, ...) *not* to be recognized as whitespace.)

* docutils/utils/smartquotes.py:

  - Update quote definitions for et, fi, fr, ro, sv, tr, uk.
  - Add quote definitions for hr, hsb, hu, lv, sh, sl, sr.
  - Differentiate apostrophe from closing single quote (if possible).
  - Add command line interface for stand-alone use (requires 2.7).

* docutils/writers/_html_base:

  - Provide default title in metadata.
  - The MathJax CDN shut down on April 30, 2017. For security reasons, we
    don't use a third party public installation as default but warn
    if `math-output` is set to MathJax without specifying a URL.
    See math-output_ for details.

* docutils/writers/html4css1:

  - Respect automatic table column sizing.

* docutils/writers/latex2e/__init__.py

  - Handle class arguments for block-level elements by wrapping them
    in a "DUclass" environment. This replaces the special handling for
    "epigraph" and "topic" elements.

* docutils/writers/odf_odt:

  - Language option sets ODF document's default language
  - Image width, scale, ... set image size in generated ODF.

* tools/

  - New front-end ``rst2html4.py``.

cheers

Re: [Docutils-users] How stable is reStructuredText format?

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

On Tue, Aug 1, 2017 at 2:31 AM, crocket <cro...@gm...> wrote:
> Will there be breaking changes in reStructuredText in the foreseeable
> future?

No.

Ongoing backward compatibility is of paramount importance in Docutils
and the reStructuredText format definition. Any changes made are
additions (new constructs which would have failed in the past) or
corrections (fixing bugs). Documents from years ago still process
properly, using the latest Docutils code.

These days changes/additions are infrequent, incremental, and
discussed thoroughly on the Docutils-develop mailing list first.

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

Re: [Docutils-users] How stable is reStructuredText format?

[Ben F. <ben...@be...>]

crocket <cro...@gm...> writes:

> Will there be breaking changes in reStructuredText in the foreseeable
> future?

The reStructuredText *format* was fixed many years ago, and I'm not
aware of any proposed newer versions.

In fact, I am not aware of any releases of “reStructuredText” in the
past ten years. So I'm not sure what changes you're asking about.

-- 
 \                   “The best ad-libs are rehearsed.” —Graham Kennedy |
  `\                                                                   |
_o__)                                                                  |
Ben Finney

Re: [Docutils-users] How stable is reStructuredText format?

[crocket <cro...@gm...>]

Will there be breaking changes in reStructuredText in the foreseeable
future?

On Mon, Jul 31, 2017 at 10:27 PM, Roberto Alsina <ra...@kd...> wrote:

> On Mon, Jul 31, 2017 at 5:31 AM crocket <cro...@gm...> wrote:
>
>> If I wrote a document in reStructuredText, how long can I expect it to
>> last?
>>
>>
> It depends.
>
> Will there be a stable, maintained toolchain to process your text in 100
> years? Probably not.
>
> Will there be a stable, maintained tool to view the HTML or PDF output of
> your text in 100 years? Probably yes, because there are enough things that
> need to live a long time in those formats.
>
> Will there be a stable, maintained tool to open text files in 100 years?
> Most likely.
>
> If you change those "100" to lower numbers, each one becomes more likely.
>

Re: [Docutils-users] Pull dictionary of docinfo fields from a document?

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

On July 31, 2017 at 3:03:49 AM, Guenter Milde via Docutils-users (
doc...@li...) wrote:

On 2017-07-30, Tony Narlock wrote:

> My intention is to use DocInfo as a way to scape meta information off RST
> files to build an index of them.

> There is a DocInfo transformer at docinfo.transforms.frontmatter.DocInfo.

> Two things:

> 1. I don’t want DocInfo fields to show on HTMLWriter

Either hide them with CSS or strip with the setting:

--strip-elements-with-class=<class>
Remove all elements with classes="<class>" from the
document tree. Warning: potentially dangerous; use
with caution. (Multiple-use option.)

Thanks, I gave both those a shot in my initial run. After a bit more
digging, I was able to do this by overriding visit_docinfo in the
HTMLWriter:

    def visit_docinfo(self, node):

        raise nodes.SkipNode




> 2. I want to pull a python dictionary of key->value fields from DocInfo.

...

> My understanding is DocInfo handles that fields in biblio_nodes, but also
> can handle arbitrary field names. (
> http://docutils.sourceforge.net/docs/ref/doctree.html#docinfo). Is that
> true?

Yes.

Check with, e.g. rst2pseudoxml, this gives a nice representation of the
doctree. Then you can, e.g. create a function to convert the docinfo
sub-tree into the dict. The transforms will give some hints on how to wald
around the doctree and collect information.

That helped.

In my circumstance, I was able to find some permissively licensed code that
did a .traverse(nodes.docinfo) to pluck out a dict of the information.

Here is the snippet:
https://github.com/adieu/mezzanine-cli/blob/c6feeaf/mezzanine_cli/parser.py#L17

License: https://github.com/adieu/mezzanine-cli/blob/c6feeaf/setup.py#L10



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.

[Docutils-users] Return reStructuredText source content after title, subtitle, and docinfo

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

I want to be able to store raw reStructuredText “body content”, including
section names after title/subtitle, in a database.

At present, I am using publish_doctree to get title, subtitle, and docinfo
meta data successfully.

So, assuming:


==========
Main title
==========
Subtitle
========

:Date: 2017-04-04


I want everything from this segment and below

Including sections
“”””””””””””””””””

like this


I just want to get this:

I want everything from this segment and below

Including sections
“”””””””””””””””””

like this

I want the raw reStructuredText to be preserved.

Re: [Docutils-users] How stable is reStructuredText format?

[Roberto A. <ra...@kd...>]

On Mon, Jul 31, 2017 at 5:31 AM crocket <cro...@gm...> wrote:

> If I wrote a document in reStructuredText, how long can I expect it to
> last?
>
>
It depends.

Will there be a stable, maintained toolchain to process your text in 100
years? Probably not.

Will there be a stable, maintained tool to view the HTML or PDF output of
your text in 100 years? Probably yes, because there are enough things that
need to live a long time in those formats.

Will there be a stable, maintained tool to open text files in 100 years?
Most likely.

If you change those "100" to lower numbers, each one becomes more likely.