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

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.

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

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

On 2017-07-31, 08:31 GMT, crocket wrote:
> If I wrote a document in reStructuredText, how long can I expect it to last?

Longer than the latest version of Microsoft Word and probably 
longer than with one of various versions of Markdown. Do you 
still have those Lotus Ami Pro documents? Just next to the Word 
2.0 ones? Right.

Best,

Matěj
-- 
http://matej.ceplovi.cz/blog/, Jabber: mcepl<at>ceplovi.cz
GPG Finger: 3C76 A027 CA45 AD70 98B5  BC1D 7920 5802 880B C9D8
 
As a rule of thumb, the more qualifiers there are before the name
of a country, the more corrupt the rulers. A country called The
Socialist People's Democratic Republic of X is probably the last
place in the world you'd want to live.
    -- Paul Graham discussing (not only) Nigerian spam
       (http://www.paulgraham.com/spam.html)

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

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

I forgot to send a reply to all recipients. This email is sent to all
recipients. I am looking for a lightweight markup language suitable for
writing diary and taking notes.
Once I write a diary entry, I want to keep it for many decades without
modification.
If I had to manually modify them after decades, then I would be tempted to
treat them as .txt files and not bother to compile them.

On Mon, Jul 31, 2017 at 5:35 PM, engelbert gruber <
eng...@gm...> wrote:

> https://www.openhub.net/p/docutils
>
> i would say ... rock class
>
> On 31 July 2017 at 10:31, crocket <cro...@gm...> wrote:
>
>> If I wrote a document in reStructuredText, how long can I expect it to
>> last?
>>
>> ------------------------------------------------------------
>> ------------------
>> 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] How stable is reStructuredText format?

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

https://www.openhub.net/p/docutils

i would say ... rock class

On 31 July 2017 at 10:31, crocket <cro...@gm...> wrote:

> If I wrote a document in reStructuredText, how long can I expect it to
> last?
>
> ------------------------------------------------------------
> ------------------
> 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] How stable is reStructuredText format?

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

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

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

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

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


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

Günter

Re: [Docutils-users] publish_parts and table of contents?

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

On July 26, 2017 at 2:03:02 AM, Guenter Milde via Docutils-users (
doc...@li...) wrote:

On 2017-07-25, Tony Narlock wrote:

> What if the user doesn’t want to publish CSS from the tree?

You can select the used CSS stylsheet(s) as well as toggle between
inclusion and referencing them via Docutils settings.
For programmatic use, "settings_override" is your friend.

See "config.html" and the documentation the publish_* functions for
descriptions and, e.g., the functional tests for usage examples.


> Even if using
> publish_doctree, I prefer the equivalent to publish_parts fragment and
> html_body, usually.


> Here is what I did:

...

> Is the equivalent of this attainable a simpler way? Is something like this
> worth considering as a patch?

I don't know. You may file an enhancement ticket.

Considering that.



Also the addition of "contents" as a part for the HTML writer seems like a
valid enhancement request. (But mind that we don't have many ressources to
really work on it.)

The ToC is being used on a production website right now, I plan on making a
post about how the site uses docutils.

I’m trying to get myself into gear on docutils internals so I can help now
and then.



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] Pull dictionary of docinfo fields from a document?

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

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
2. I want to pull a python dictionary of key->value fields from DocInfo.

e.g.

==============
Document title
==============

:date: 2017-05-01
:custom_field: value

rest of the file

Being able to extract:

{
    "date": datetime.date(2017,5,1),
    "custom_field": "value"
}


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?

Re: [Docutils-users] publish_parts and table of contents?

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

On 2017-07-25, Tony Narlock wrote:

> What if the user doesn’t want to publish CSS from the tree? 

You can select the used CSS stylsheet(s) as well as toggle between
inclusion and referencing them via Docutils settings.
For programmatic use, "settings_override" is your friend.

See "config.html" and the documentation the publish_* functions for
descriptions and, e.g., the functional tests for usage examples.


> Even if using
> publish_doctree, I prefer the equivalent to publish_parts fragment and
> html_body, usually.


> Here is what I did:

...

> Is the equivalent of this attainable a simpler way? Is something like this
> worth considering as a patch?

I don't know. You may file an enhancement ticket.

Also the addition of "contents" as a part for the HTML writer seems like a
valid enhancement request. (But mind that we don't have many ressources to
really work on it.)

Günter

Re: [Docutils-users] publish_parts and table of contents?

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

Thank you. This has been educational and shown me things that I didn’t find
obvious.

What if the user doesn’t want to publish CSS from the tree?  Even if using
publish_doctree, I prefer the equivalent to publish_parts fragment and
html_body, usually.

Here is what I did:

def publish_parts_from_doctree(document, destination_path=None,
                               writer=None, writer_name='pseudoxml',
                               settings=None, settings_spec=None,
                               settings_overrides=None, config_section=None,
                               enable_exit_status=False):
    reader = docutils.readers.doctree.Reader(parser_name='null')
    pub = Publisher(reader, None, writer,
                    source=io.DocTreeInput(document),
                    destination_class=io.StringOutput, settings=settings)
    if not writer and writer_name:
        pub.set_writer(writer_name)
    pub.process_programmatic_settings(
        settings_spec, settings_overrides, config_section)
    pub.set_destination(None, destination_path)
    pub.publish(enable_exit_status=enable_exit_status)
    return pub.writer.parts


Is the equivalent of this attainable a simpler way? Is something like this
worth considering as a patch?

On July 24, 2017 at 9:08:59 AM, Guenter Milde via Docutils-users (
doc...@li...) wrote:

On 2017-07-22, Tony Narlock wrote:

> I can confirm getting the node information.

> The issue I have is getting the HTML from toc_list.

> The only other problem I have is:

...
> AttributeError: 'bullet_list' object has no attribute
> 'note_transform_message'

You need to pass a complete doctree to publish from doctree but
transforms.Contents.build_contents() returns only a partial doctree.

The example below should get you started.

Günter

#! /usr/bin/env python
# -*- coding: utf-8 -*-
#
# Proof of concept for a front end generating just a toc from an rst source.

import sys
import docutils
from docutils.core import Publisher, publish_doctree, publish_from_doctree
from docutils.transforms.parts import Contents
from docutils import nodes
# from docutils.writers.html5_polyglot import Writer

# Test source as string
sample = """

Sample Title
============

first section
-------------

some text

second section
--------------

more text

this is subsection 2.1
**********************

"""

# Parse sample to a doctree (for later parsing with build_contents())

sample_tree = publish_doctree(source=sample)

# The sample can also be written to supported output formats from the
doctree:
output = publish_from_doctree(sample_tree, writer_name="pseudoxml")
# output = publish_from_doctree(sample_tree, writer_name="latex")
# output = publish_from_doctree(sample_tree, writer_name="html5")

#print output


# Create a new document tree with just the table of contents
# ==========================================================

# document tree template:
toc_tree = nodes.document('', '', source='toc-generator')
toc_tree += nodes.title('', 'Table of Contents')

# Re-use the Contents transform to generate the toc by travelling over the
# doctree of the complete document.

# Set up a Contents instance:
# The Contents transform requires a "pending" startnode and generation
options
# startnode
pending = nodes.pending(Contents, rawsource='')
contents_transform = docutils.transforms.parts.Contents(sample_tree,
pending)
contents_transform.backlinks = False

# run the contents builder and append the result to the template:
toc_topic = nodes.topic(classes=['contents'])
toc_topic += contents_transform.build_contents(sample_tree)

toc_tree += toc_topic

# test

# print toc_tree
output = publish_from_doctree(toc_tree, writer_name="pseudoxml")
output = publish_from_doctree(toc_tree, writer_name="html5")
print output


------------------------------------------------------------------------------
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] publish_parts and table of contents?

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

On 2017-07-22, Tony Narlock wrote:

> I can confirm getting the node information.

> The issue I have is getting the HTML from toc_list.

> The only other problem I have is:

...
> AttributeError: 'bullet_list' object has no attribute
> 'note_transform_message'

You need to pass a complete doctree to publish from doctree but
transforms.Contents.build_contents() returns only a partial doctree.

The example below should get you started.

Günter

#! /usr/bin/env python
# -*- coding: utf-8 -*-
#
# Proof of concept for a front end generating just a toc from an rst source.

import sys
import docutils
from docutils.core import Publisher, publish_doctree, publish_from_doctree
from docutils.transforms.parts import Contents
from docutils import nodes
# from docutils.writers.html5_polyglot import Writer

# Test source as string
sample = """

Sample Title
============

first section
-------------

some text

second section
--------------

more text

this is subsection 2.1
**********************

"""

# Parse sample to a doctree (for later parsing with build_contents())

sample_tree = publish_doctree(source=sample)

# The sample can also be written to supported output formats from the doctree:
output = publish_from_doctree(sample_tree, writer_name="pseudoxml")
# output = publish_from_doctree(sample_tree, writer_name="latex")
# output = publish_from_doctree(sample_tree, writer_name="html5")

#print output


# Create a new document tree with just the table of contents
# ==========================================================

# document tree template:
toc_tree = nodes.document('', '', source='toc-generator')
toc_tree += nodes.title('', 'Table of Contents')

# Re-use the Contents transform to generate the toc by travelling over the
# doctree of the complete document.

# Set up a Contents instance:
# The Contents transform requires a "pending" startnode and generation options
# startnode
pending = nodes.pending(Contents, rawsource='')
contents_transform = docutils.transforms.parts.Contents(sample_tree, pending)
contents_transform.backlinks = False

# run the contents builder and append the result to the template:
toc_topic = nodes.topic(classes=['contents'])
toc_topic += contents_transform.build_contents(sample_tree)

toc_tree += toc_topic

# test

# print toc_tree
output = publish_from_doctree(toc_tree, writer_name="pseudoxml")
output = publish_from_doctree(toc_tree, writer_name="html5")
print output

Re: [Docutils-users] publish_parts and table of contents?

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

I can confirm getting the node information.

The issue I have is getting the HTML from toc_list.

The only other problem I have is:

from docutils.writers.html5_polyglot import Writer
core.publish_from_doctree(toc_list, writer=Writer())

Traceback (most recent call last):
  File “./try2.py", line 48, in <module>
    core.publish_from_doctree(toc_list, writer=Writer())
  File ".venv/lib/python3.6/site-packages/docutils/core.py", line 521, in
publish_from_doctree
    return pub.publish(enable_exit_status=enable_exit_status)
  File ".venv/lib/python3.6/site-packages/docutils/core.py", line 218, in
publish
    self.apply_transforms()
  File ".venv/lib/python3.6/site-packages/docutils/core.py", line 199, in
apply_transforms
    self.document.transformer.apply_transforms()
  File “.venv/lib/python3.6/site-packages/docutils/transforms/__init__.py",
line 162, in apply_transforms
    self.document.note_transform_message)
AttributeError: 'bullet_list' object has no attribute
'note_transform_message'


On July 21, 2017 at 10:40:53 PM, David Goodger (go...@py...) wrote:

On Fri, Jul 21, 2017 at 7:41 PM, Tony Narlock <to...@gi...> wrote:
> Thanks for your help on this.
>
> This is way trickier than it looks, with all due respect.

Just because you're trying to hack Docutils without a sufficiently
deep understanding of the internals.

> Clocked in almost
> two days on this so far.

Hopefully this exercise has improved your understanding!

> Just trying to get the table of contents separate from html_body.
Seriously
> considering adding ..contents:: to the source, building HTML and ripping
out
> the ToC via LXML.
>
> Love reStructuredText and docutils (been having quite a few internal
> successes lately), but this particular task feels like going against the
> grain.

Have you read the documentation? There's no one place for what you
want, it's spread out. See:

* http://docutils.sourceforge.net/docs/ref/transforms.html
* http://docutils.sourceforge.net/docs/peps/pep-0258.html#transformer
* http://docutils.sourceforge.net/docs/dev/hacking.html

Also, see the code. There's lots of inline documentation in docstrings
and comments.

Ultimately, you need to understand the flow of data in Docutils, how
all the components interrelate.

No, no, no, don't tug on that. You never know what it might be attached to.

— Buckaroo Banzai (during brain surgery)

I think the attached code will get you most of the way to where you want to
go.

DG


> On July 21, 2017 at 3:39:58 PM, Guenter Milde via Docutils-users
> (doc...@li...) wrote:
>
> On 2017-07-21, Tony Narlock wrote:
>
>> So here is where I am:
>> https://gist.github.com/tony/1a03b7668c9e33672f4465dd63c6076b
>
> No time to look.
>
>> On July 20, 2017 at 11:54:07 AM, Guenter Milde via Docutils-users (
>> On 2017-07-20, Tony Narlock wrote:
>>> On July 19, 2017 at 5:27:15 PM, Guenter Milde via Docutils-users (
>
>>> ...
>
>
>> > I suppose rather than messing with "parts", you can use the publish_*
>> > functions in a wrapper script:
>>
>> > Don't use ``.. contents..`` in the source.
>>
>> > 1. Parse the rst source with publish_doctree()
>>
>> > Returns a doctree object.
>>
>>
>> > 2. Export doctree to HTML with publish_from_doctree()
>
> Does this work?
>
> Yes, this just gives CSS + HTML for way more than I need. Am I supposed
to
> see anything special in the HTML or are you just checking that
> publish_doctree+publish_from_doctree works (it does).
>
> Way more than html_body (all I need, aside from ToC). And I’m not sure
what
> I can do with this content?
>
>
>
>
>> > 3. Run the toc-generating transform on the doctree.
>> > Returns a "toc doctree".
>
>> Where would it be?
>
> In docutils/transforms/parts.py
>
>
>
>> Am I applying the transform correctly in the paste?
>
>>> 4. Export the "toc doctree" with publish_from_doctree().
>
>> Assuming I’m running the transform correctly, I see no difference in the
>> output.
>
> So I suppose you don't apply it correctly.
>
> The idea is to collect generate a TOC by travelling over the doctree in
> the same manner as it is done by the "Contents" transform.
>
> Therefore, it should be possible to use
> docutils.transforms.parts.Contents.build_contents() and pass it the
> startnode of the doctree returned by "publish_parts".
>
>>> This is just an idea, not tested and detailled.
>
> Günter

Re: [Docutils-users] publish_parts and table of contents?

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

On 2017-07-22, 03:40 GMT, David Goodger wrote:
> On Fri, Jul 21, 2017 at 7:41 PM, Tony Narlock <to...@gi...> wrote:
>> Thanks for your help on this.
>>
>> This is way trickier than it looks, with all due respect.
>
> Just because you're trying to hack Docutils without a sufficiently
> deep understanding of the internals.

Yeah, but that’s the problem for most people who would like to 
hack on docutils. I am following this thread with some level of 
dread, because these are exactly operations I will probably need 
if I am thinking about writing that rst2epub. And frankly this 
thread does not increase my faith in my own ability to write 
such script (if I had the time to do so, that is).

I will certainly study your attached example.

Best,

Matěj
-- 
http://matej.ceplovi.cz/blog/, Jabber: mcepl<at>ceplovi.cz
GPG Finger: 3C76 A027 CA45 AD70 98B5  BC1D 7920 5802 880B C9D8
 
He uses statistics as a drunken man uses lamp-posts... for
support, rather than illumination.
      -- Andrew Lang

Re: [Docutils-users] publish_parts and table of contents?

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

On Fri, Jul 21, 2017 at 7:41 PM, Tony Narlock <to...@gi...> wrote:
> Thanks for your help on this.
>
> This is way trickier than it looks, with all due respect.

Just because you're trying to hack Docutils without a sufficiently
deep understanding of the internals.

> Clocked in almost
> two days on this so far.

Hopefully this exercise has improved your understanding!

> Just trying to get the table of contents separate from html_body.  Seriously
> considering adding ..contents:: to the source, building HTML and ripping out
> the ToC via LXML.
>
> Love reStructuredText and docutils (been having quite a few internal
> successes lately), but this particular task feels like going against the
> grain.

Have you read the documentation? There's no one place for what you
want, it's spread out. See:

* http://docutils.sourceforge.net/docs/ref/transforms.html
* http://docutils.sourceforge.net/docs/peps/pep-0258.html#transformer
* http://docutils.sourceforge.net/docs/dev/hacking.html

Also, see the code. There's lots of inline documentation in docstrings
and comments.

Ultimately, you need to understand the flow of data in Docutils, how
all the components interrelate.

    No, no, no, don't tug on that. You never know what it might be attached to.

    — Buckaroo Banzai (during brain surgery)

I think the attached code will get you most of the way to where you want to go.

DG


> On July 21, 2017 at 3:39:58 PM, Guenter Milde via Docutils-users
> (doc...@li...) wrote:
>
> On 2017-07-21, Tony Narlock wrote:
>
>> So here is where I am:
>> https://gist.github.com/tony/1a03b7668c9e33672f4465dd63c6076b
>
> No time to look.
>
>> On July 20, 2017 at 11:54:07 AM, Guenter Milde via Docutils-users (
>> On 2017-07-20, Tony Narlock wrote:
>>> On July 19, 2017 at 5:27:15 PM, Guenter Milde via Docutils-users (
>
>>> ...
>
>
>> > I suppose rather than messing with "parts", you can use the publish_*
>> > functions in a wrapper script:
>>
>> > Don't use ``.. contents..`` in the source.
>>
>> > 1. Parse the rst source with publish_doctree()
>>
>> > Returns a doctree object.
>>
>>
>> > 2. Export doctree to HTML with publish_from_doctree()
>
> Does this work?
>
> Yes, this just gives CSS + HTML for way more than I need. Am I supposed to
> see anything special in the HTML or are you just checking that
> publish_doctree+publish_from_doctree works (it does).
>
> Way more than html_body (all I need, aside from ToC). And I’m not sure what
> I can do with this content?
>
>
>
>
>> > 3. Run the toc-generating transform on the doctree.
>> > Returns a "toc doctree".
>
>> Where would it be?
>
> In docutils/transforms/parts.py
>
>
>
>> Am I applying the transform correctly in the paste?
>
>>> 4. Export the "toc doctree" with publish_from_doctree().
>
>> Assuming I’m running the transform correctly, I see no difference in the
>> output.
>
> So I suppose you don't apply it correctly.
>
> The idea is to collect generate a TOC by travelling over the doctree in
> the same manner as it is done by the "Contents" transform.
>
> Therefore, it should be possible to use
> docutils.transforms.parts.Contents.build_contents() and pass it the
> startnode of the doctree returned by "publish_parts".
>
>>> This is just an idea, not tested and detailled.
>
> Günter

Re: [Docutils-users] publish_parts and table of contents?

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

Thanks for your help on this.

This is *way* trickier than it looks, with all due respect. Clocked in
almost two days on this so far.

Just trying to get the table of contents separate from html_body.
Seriously considering adding ..contents:: to the source, building HTML and
ripping out the ToC via LXML.

Love reStructuredText and docutils (been having quite a few internal
successes lately), but this particular task feels like going against the
grain.

On July 21, 2017 at 3:39:58 PM, Guenter Milde via Docutils-users (
doc...@li...) wrote:

On 2017-07-21, Tony Narlock wrote:

> So here is where I am:
> https://gist.github.com/tony/1a03b7668c9e33672f4465dd63c6076b

No time to look.

> On July 20, 2017 at 11:54:07 AM, Guenter Milde via Docutils-users (
> On 2017-07-20, Tony Narlock wrote:
>> On July 19, 2017 at 5:27:15 PM, Guenter Milde via Docutils-users (

>> ...


> > I suppose rather than messing with "parts", you can use the publish_*
> > functions in a wrapper script:
>
> > Don't use ``.. contents..`` in the source.
>
> > 1. Parse the rst source with publish_doctree()
>
> > Returns a doctree object.
>
>
> > 2. Export doctree to HTML with publish_from_doctree()

Does this work?

Yes, this just gives CSS + HTML for way more than I need. Am I supposed to
see anything special in the HTML or are you just checking that
publish_doctree+publish_from_doctree works (it does).

Way more than html_body (all I need, aside from ToC). And I’m not sure what
I can do with this content?




> > 3. Run the toc-generating transform on the doctree.
> > Returns a "toc doctree".

> Where would it be?

In docutils/transforms/parts.py



> Am I applying the transform correctly in the paste?

>> 4. Export the "toc doctree" with publish_from_doctree().

> Assuming I’m running the transform correctly, I see no difference in the
> output.

So I suppose you don't apply it correctly.

The idea is to collect generate a TOC by travelling over the doctree in
the same manner as it is done by the "Contents" transform.

Therefore, it should be possible to use
docutils.transforms.parts.Contents.build_contents() and pass it the
startnode of the doctree returned by "publish_parts".

>> This is just an idea, not tested and detailled.

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.