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

Re: [Docutils-users] Inline, verbatim anchors?

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

On 2019-10-08, Guenter Milde via Docutils-users wrote:
> On 2019-10-07, Matthew Woehlke wrote:
>> On 07/10/2019 14.11, Guenter Milde via Docutils-users wrote:
>>> On 2019-10-07, Matthew Woehlke wrote:

>>>> What I want, ideally, is a role that takes its text and generates an
>>>> anchor from its text (i.e. sets the 'id' on its node to its contents),
>>>> *and also emits the text*.

>>> You may be looking for `inline internal targets`__.

>>> __ http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#inline-internal-targets

>> Huh. Okay, that *sort of* works, but is there any way to style the text?

> Unfortunately, inline markup nesting is not supported.
> This is a long standing feature request.
> http://docutils.sourceforge.net/docs/dev/todo.html#nested-inline-markup


Another option would be to extend `custom interpreted text roles`_ to roles
based on hyperlink targets and hyperlink references.

__ http://docutils.sourceforge.net/docs/ref/rst/directives.html#custom-interpreted-text-roles

Concept: 
  Two special roles :hyperlink-reference: and :hyperlink-target: are
  defined (similar to the `:raw:`__ role).

  __ http://docutils.sourceforge.net/docs/ref/rst/roles.html#raw
	 
  Then, the rSText::
	 
    .. role:: emph-link(hyperlink-target)
    
    :emph-link:`here`
    
  would create a target with class argument::
  
        <target ids="target" names="target" classes="emph-link">
            target

  that could be styled accordingly.


Maybe we could also allow a combination of hyperlink syntax and role syntax
like::

  This is an _`important target`:emphasis: and a very :strong:`bold link`_.
  
This makes use of the fact that the `interpreted text`__ role can be
specified on either side.

__ http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#interpreted-text


Günter



Günter

Re: [Docutils-users] Set Debug Mode?

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

On 2019-10-08, Kent Borg wrote:
> I have discovered that setting debug=True in the 
> statemachine.StateMachine.__init__() call can be *very* useful. But I'm 
> not calling directly. Tracing my call stack is seems to be 
> reader/__init__.py Reader.parse() that would be the place to pass it 
> down that doesn't.

> Is there a way to set that programmaticly? I can edit statemachine.py to 
> force it, but that's both ugly and obscure. Is there a better way that I 
> missed?

"debug" is one of the many configuration settings
http://docutils.sourceforge.net/docs/user/config.html#debug

You can either set it in a local configuration file, or via the
`settings_overrides` argument to the `core.publish_*()` functions, e.g.

  parts = docutils.core.publish_parts(...
  	  			      settings_overrides={debug: True})

See the Docutils test suite for code examples and
http://docutils.sourceforge.net/docs/api/publisher.html
for general documentation on use of Docutils as a library.

Günter

[Docutils-users] Set Debug Mode?

[Kent B. <ken...@bo...>]

I have discovered that setting debug=True in the 
statemachine.StateMachine.__init__() call can be *very* useful. But I'm 
not calling directly. Tracing my call stack is seems to be 
reader/__init__.py Reader.parse() that would be the place to pass it 
down that doesn't.

Is there a way to set that programmaticly? I can edit statemachine.py to 
force it, but that's both ugly and obscure. Is there a better way that I 
missed?

Thanks,

-kb

Re: [Docutils-users] Inline, verbatim anchors?

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

On 2019-10-07, Matthew Woehlke wrote:
> On 07/10/2019 14.11, Guenter Milde via Docutils-users wrote:
>> On 2019-10-07, Matthew Woehlke wrote:

>>> What I want, ideally, is a role that takes its text and generates an
>>> anchor from its text (i.e. sets the 'id' on its node to its contents),
>>> *and also emits the text*.

>> You may be looking for `inline internal targets`__.

>> __ http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#inline-internal-targets

> Huh. Okay, that *sort of* works, but is there any way to style the text?

Unfortunately, inline markup nesting is not supported.
This is a long standing feature request.
http://docutils.sourceforge.net/docs/dev/todo.html#nested-inline-markup

> Also, the replacement of '.' with '-' is undesired and doesn't seem to
> be necessary...

The replacement is done in the ID, but not in the text or the "name" used
for references to this target from other places in the rST document:

   This is the _`inline.target`
   
   I can link to it with `inline.target`_ in the rST source document.
   
   Other documents link to it as ``file:foo.html#inline-target``
   

The rationale was to make the ID compatible with both, HTML4.1 and CSS1
identifiers:
http://docutils.sourceforge.net/docs/ref/rst/directives.html#rationale

There is a feature request to lift these limitations
https://sourceforge.net/p/docutils/feature-requests/66/
but we have to think about backwards compatibility
(it would be a bad thing if re-compiling a document would break external
links to it adapted to the current transformation without advance warning)
and other output formats (LaTeX, manpage, ODT).

Günter

Re: [Docutils-users] Inline, verbatim anchors?

[Matthew W. <mwo...@gm...>]

On 07/10/2019 14.11, Guenter Milde via Docutils-users wrote:
> On 2019-10-07, Matthew Woehlke wrote:
> 
>> What I want, ideally, is a role that takes its text and generates an
>> anchor from its text (i.e. sets the 'id' on its node to its contents),
>> *and also emits the text*.
> 
> You may be looking for `inline internal targets`__.
> 
> __ http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#inline-internal-targets

Huh. Okay, that *sort of* works, but is there any way to style the text?
Also, the replacement of '.' with '-' is undesired and doesn't seem to
be necessary...

-- 
Matthew

Re: [Docutils-users] Inline, verbatim anchors?

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

On 2019-10-07, Matthew Woehlke wrote:

> What I want, ideally, is a role that takes its text and generates an
> anchor from its text (i.e. sets the 'id' on its node to its contents),
> *and also emits the text*.

You may be looking for `inline internal targets`__.

__ http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#inline-internal-targets

Günter

[Docutils-users] Inline, verbatim anchors?

[Matthew W. <mwo...@gm...>]

I have a document that is structured roughly like the C++ standard, e.g.:


  Some Heading [foo]
  ------------------

  [foo.dog] This is a paragraph with some text.

  [foo.cat] This is another paragraph.

I want to be able to link to specific paragraphs, i.e.
https://example.com/docs/foo.html#foo.bar.

Is there any way to accomplish this? Would a patch to add a feature like
this be accepted?

What I want, ideally, is a role that takes its text and generates an
anchor from its text (i.e. sets the 'id' on its node to its contents),
*and also emits the text*. I don't want to repeat__ the section
identifiers, i.e. not this:

  .. _foo.dog

  [foo.dog] Text goes here

I also want to be able to use this "anywhere", not just before
paragraphs. (In particular, much of my document is structured as lists...)

__ https://en.wikipedia.org/wiki/Don%27t_repeat_yourself

-- 
Matthew

Re: [Docutils-users] Question About Section Levels

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

The way I would go about something like this is to write a new directive,
"insert" or "subdoc", which spawns a new parser, parses the external
subdocument file into a separate document tree, and grafts this doctree
onto the master document tree. That would allow independent section
structure in the subdocument. There are issues to consider here, like how
much context is to be copied over between the master document's parser and
the subparser (e.g. the section title adornments should not be copied over;
but what about reference names, substitution definitions, etc.?).

There are lots of notes on this (and many other topics) in the Docutils To
Do List:
http://docutils.sourceforge.net/docs/dev/todo.html#large-documents
Note: many items in there may be stale, as it hasn't been updated/pruned in
a while.

David Goodger
<https://david.goodger.org>

Re: [Docutils-users] Question About Section Levels

[Kent B. <ken...@bo...>]

On 10/2/19 4:02 PM, Guenter Milde via Docutils-users wrote:
> implementation sketch:
> * a new option to "include"::
>
>     :relative-section-levels: <offset>
>
> * push the current level and adornment-style--level mapping,
>
> * read the to-be-included file into a list and append an "end marker",
>
> * start a new adornment-style--level mapping
>
> * section_level = parent_level + offset + child_level
>
> * when hitting "end marker": pop section level and adornment-style--level
>    mapping

I don't know the code well, but that seems familiar from what I do know.

Though it seems it would be much harder to do as a custom 
directive--that is, not forking sources, not moving to a new library 
version, etc.

It turns out we have a good (AKA, really unpleasant but we have to do it 
anyway) "workaround": being compatible with some old code means we are 
chopping up content into small enough pieces that we can mostly not have 
our includes do any sections, so we can do them all in a top-level 
document that we can create on-the-fly.

A related question: What are prospects for writing a custom directive 
that does a single section, at an offset-from-current? Or, put another 
way, is there a way from the perspective of a custom directive's 
parse-time code to learn the current section level? If I knew the 
current level I could do a fake include of the right ASCII to indicate 
the section I want to create.

Thanks,

-kb, the Kent who is a big fan of fake includes to do all kinds of things.

Re: [Docutils-users] Question About Section Levels

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

Dear Kent,

On 2019-10-02, Kent Borg wrote:
> On 10/2/19 7:20 AM, Guenter Milde via Docutils-users wrote:

>> However, the mapping "adornment style" -> `section_level` is done "on the
>> go", i.e.  the first style encountered will be level 1, the second style
>> will be level 2, the third will be level 3, and so on.

>> http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#sections

> Ah, yes, I think I noticed that without realizing it. Interesting. And 
> for a moment I thought it might help me here, but I think not.

>> "this level":
>>    use the style of the previous section title.

>> "one deeper than the current level":
>>    use the style "established" for one level deepter by previous use.
>>    If there  is no "established" style yet, use a new style.

>> "X number of levels shallower than the current level"
>>    ! not allowed in rST !

> I think I am misunderstanding.
...

> This section I popped up 2 levels, I could have used "=" to pop up three, "`" to pop up one.

> That is what I meant by "X number of levels shallower".

Sorry, I did not read carefully.
You can go up several levels but down only one level. 


>>> Is there some option to include that will make contents relative to
>>> the depth at which the include directive appeared?
>> No. (It would be a nice thing but is non-trivial to implement.)

> Yes, I was tracing through docutils code yesterday, I agree it would be 
> non-trivial...

implementation sketch:

* a new option to "include"::

   :relative-section-levels: <offset>

* push the current level and adornment-style--level mapping,

* read the to-be-included file into a list and append an "end marker",

* start a new adornment-style--level mapping

* section_level = parent_level + offset + child_level

* when hitting "end marker": pop section level and adornment-style--level
  mapping


Günter

Re: [Docutils-users] Question About Section Levels

[Kent B. <ken...@bo...>]

On 10/2/19 7:20 AM, Guenter Milde via Docutils-users wrote:
> However, the mapping "adornment style" -> `section_level` is done "on the
> go", i.e.  the first style encountered will be level 1, the second style
> will be level 2, the third will be level 3, and so on.
>
> http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#sections

Ah, yes, I think I noticed that without realizing it. Interesting. And 
for a moment I thought it might help me here, but I think not.

> "this level":
>    use the style of the previous section title.
>
> "one deeper than the current level":
>    use the style "established" for one level deepter by previous use.
>    If there  is no "established" style yet, use a new style.
>
> "X number of levels shallower than the current level"
>    ! not allowed in rST !

I think I am misunderstanding. I can do:

Section 1
=========

Paragraph One

Section 2
---------

Paragraph Two is a level deeper.

Section 3
`````````

Paragraph Three is deeper still.

Section 4
'''''''''

Paragraph 4 is the deepest I'll go in this example.


Section 5
---------

This section I popped up 2 levels, I could have used "=" to pop up three, "`" to pop up one.

That is what I meant by "X number of levels shallower".


>> Is there some option to include that will make contents relative to
>> the depth at which the include directive appeared?
> No. (It would be a nice thing but is non-trivial to implement.)

Yes, I was tracing through docutils code yesterday, I agree it would be 
non-trivial...


This is part of the dynamic content inside RST project I mentioned a few 
weeks ago. This specific question is prompted by needed to be backwards 
compatible with a previous design. It looks like our workaround will be 
rST include files in smaller chunks. Not as nice for maintaining our 
content, but it will work.


Now I need to go make changes to one of the custom directives I wrote: 
add a section depth parameter so it can be used from any nesting depth...


Thanks,

-kb

Re: [Docutils-users] Question About Section Levels

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

On 2019-10-01, Kent Borg wrote:
> As I understand it reStructuredText section levels are absolute, not
> relative. 
> That is, at any point one can do another section at the
> current level, do a section one level deeper, or do a section
> shallower. But in each case it must be an explicit level indicated
> by an explicit underlining character.

However, the mapping "adornment style" -> `section_level` is done "on the
go", i.e.  the first style encountered will be level 1, the second style
will be level 2, the third will be level 3, and so on.

http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#sections


> Is there a way to do a section that is merely "this level" or "one
> deeper than the current level" or "X number of levels shallower than
> the current level"? That's all reStructuredText wants to know, there
> must be a way to say that...

"this level": 
  use the style of the previous section title.

"one deeper than the current level":
  use the style "established" for one level deepter by previous use.
  If there  is no "established" style yet, use a new style.

"X number of levels shallower than the current level"
  ! not allowed in rST !
  

> The use-case is to make include files useful at different
> levels. Imagine a long document with lots of detail sitting in
> different include files, and imagine an executive summary document
> that has less detail, but wants to include a specific section to
> highlight something notable, using an include file that is also used
> by the long document. Cool, no problem...but what if the section
> level in the executive summary will be shallower than in the
> detailed document?

Then, you must change the section title adornment style in one of the
documents. Unfortunately, this means advance planning of section styles
(or lookup and editing later on). A good editor__ may help (e.g. by
producing an outline showing the adornments used in a document).

__ http://docutils.sourceforge.net/docs/user/links.html#editors


> Is there some option to include that will make contents relative to
> the depth at which the include directive appeared?

No. (It would be a nice thing but is non-trivial to implement.)

> Is there some way I might make a custom directive that can do
> relative sections?

This would be tricky, because currently, the included file is
included as source replacing the "include" directive and then parsing
continues (i.e. the result is the same as if the file content were
inserted into the master file before calling Docutils).


Thanks,

Günter

[Docutils-users] Question About Section Levels

[Kent B. <ken...@bo...>]

As I understand it reStructuredText section levels are absolute, not
relative. That is, at any point one can do another section at the
current level, do a section one level deeper, or do a section
shallower. But in each case it must be an explicit level indicated
by an explicit underlining character.

Is there a way to do a section that is merely "this level" or "one
deeper than the current level" or "X number of levels shallower than
the current level"? That's all reStructuredText wants to know, there
must be a way to say that...

The use-case is to make include files useful at different
levels. Imagine a long document with lots of detail sitting in
different include files, and imagine an executive summary document
that has less detail, but wants to include a specific section to
highlight something notable, using an include file that is also used
by the long document. Cool, no problem...but what if the section
level in the executive summary will be shallower than in the
detailed document?

Is there some option to include that will make contents relative to
the depth at which the include directive appeared?

Is there some way I might make a custom directive that can do
relative sections?

Thanks,

-kb

Re: [Docutils-users] CSV Table with code block inside a column

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

A sample of reST from the test suite is below (if the indentation doesn't
come through, see [1]_). The third column of the header and the first
column of the table body row consist of multi-line block markup, in this
case bullet lists. Note that between quotation marks, line breaks are
significant. All lines must be indented, and the greatest common
indentation is removed.

.. csv-table:: complex internal structure
   :header: "Treat", Quantity, "
            * Description,
            * Definition, or
            * Narrative"

   "
   * Ice cream
   * Sorbet
   * Albatross", 2.99, "On a stick!"

.. [1]
https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/test/test_parsers/test_rst/test_directives/test_tables.py

David Goodger
<https://david.goodger.org>


On Thu, 26 Sep 2019 at 22:32, jacques yakoub <jac...@ho...>
wrote:

> Hello,
>
> I would like to insert a code-block inside this csv table (inside the
> "code" column ).
>
> .. csv-table:: Compilations errors
>     :header: "File","Line","Error Message","Code"
>     :widths: auto
>
> As explained in the docs (
> http://docutils.sourceforge.net/docs/ref/rst/directives.html#id4 )  : "
>
> *Block markup and inline markup within cells is supported. Line ends are
> recognized within cells.*",
>
> I would like to use an block markup so that I can replace it with the
> right code-block later ( the code could be on multiple lines ). Can you
> give me a code sample for this situation, if it is possible ?
>
> If not, feel free to suggest an alternative as I should programmatically
> generate this code in python.
>
> Thanks for your help.
>
> Jacques
> _______________________________________________
> 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] CSV Table with code block inside a column

[jacques y. <jac...@ho...>]

Hello,

I would like to insert a code-block inside this csv table (inside the "code" column ).

.. csv-table:: Compilations errors
    :header: "File","Line","Error Message","Code"
    :widths: auto

As explained in the docs ( http://docutils.sourceforge.net/docs/ref/rst/directives.html#id4 )  : "

Block markup and inline markup within cells is supported. Line ends are recognized within cells.",

I would like to use an block markup so that I can replace it with the right code-block later ( the code could be on multiple lines ). Can you give me a code sample for this situation, if it is possible ?

If not, feel free to suggest an alternative as I should programmatically generate this code in python.

Thanks for your help.

Jacques

Re: [Docutils-users] Inline markup status

[Saša J. <sja...@gm...>]

On Tue, 10 Sep 2019 11:50:12 +0200
Martin Koutecký <m...@ef...> wrote:

> For my purposes, it would suffice if we could have one level of nested
> inline markup: there are substitution references which serve for
> deduplication, but some occurrences of the strings are emphasized
> while other are not -- this is where I need nesting.

Just to add that I'd very happy with that as well!

At the moment I'm considering whether to use rst or asciidoc(tor) markup for
all my writings which includes study notes, web content (via
static-site-generator), articles, slide-show presentations...up to working on
full-fledged book(s).

Although rst has strange mark for some things, it's still vwery powerful and
the tooling is much lighter - recently heard that reference implementation for
Asciidoc(tor)'s spec is going to be implemented in Java which does not sound
too great for me not liking to use Java in general...


Sincerely,
Gour

-- 
The senses, the mind and the intelligence are the sitting places
of this lust. Through them lust covers the real knowledge of the
living entity and bewilders him.

[Docutils-users] Inliner.init_customizations uses locals()

[Eric H. <er...@he...>]

because Inliner.init_customizations uses locals(), it can't be used in a subclass. This breaks subclasses that override init_customizations because they can't call super(). but super.init_customizations must be called because otherwise patterns is not initialized.

For an example of how this problem required a workaround, see https://github.com/gutenbergtools/ebookmaker/pull/13 <https://github.com/gutenbergtools/ebookmaker/pull/13>


Eric Hellman
President, Free Ebook Foundation
Founder, Unglue.it https://unglue.it/
https://go-to-hellman.blogspot.com/
twitter: @gluejar

Re: [Docutils-users] Inline markup status

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

Dear Martin,

On 2019-09-10, Martin Koutecký wrote:

> I would like to ask about the current status of the inline markup feature.
> I'm aware of the reported state here:
> http://docutils.sourceforge.net/FAQ.html#is-nested-inline-markup-possible
> but I'm also curious because it doesn't mention the effort described here:
> https://sourceforge.net/p/docutils/feature-requests/22/ which seems to have
> gotten quite far. However, the patch doesn't apply against the current tree.

> For my purposes, it would suffice if we could have one level of nested
> inline markup: there are substitution references which serve for
> deduplication, but some occurrences of the strings are emphasized while
> other are not -- this is where I need nesting.

> Could you please give me a gauge of

> 1. How difficult would it be to port the patch in
> https://sourceforge.net/p/docutils/feature-requests/22/ to the current
> version?
> 2. What happened to that and the nesting branch?

Both are currently "sleeping". It may be interesting to revive them, but I
cannot tell how much work this would be.

> 3. If both above are useless / too hard, how difficult would it be to
> implement a "one level nesting" feature and whether you would be interested
> in including it, even though it falls short of the target described in the
> FAQ?

This may be a start but possibly not simpler than the original target of
recursive nesting.

Suggestions and patches are welcome, preferably in smaller steps so we can
discuss the changes "interactively".

Thanks,
Günter

[Docutils-users] Inline markup status

[Martin K. <m...@ef...>]

Hi,

I would like to ask about the current status of the inline markup feature.
I'm aware of the reported state here:
http://docutils.sourceforge.net/FAQ.html#is-nested-inline-markup-possible
but I'm also curious because it doesn't mention the effort described here:
https://sourceforge.net/p/docutils/feature-requests/22/ which seems to have
gotten quite far. However, the patch doesn't apply against the current tree.

For my purposes, it would suffice if we could have one level of nested
inline markup: there are substitution references which serve for
deduplication, but some occurrences of the strings are emphasized while
other are not -- this is where I need nesting.

Could you please give me a gauge of

1. How difficult would it be to port the patch in
https://sourceforge.net/p/docutils/feature-requests/22/ to the current
version?
2. What happened to that and the nesting branch?
3. If both above are useless / too hard, how difficult would it be to
implement a "one level nesting" feature and whether you would be interested
in including it, even though it falls short of the target described in the
FAQ?

Thanks a lot,

Martin Koutecky

Re: [Docutils-users] Writing Custom Directives, Expand Using Dynamic Data?

[Kent B. <ken...@bo...>]

On 9/2/19 9:26 AM, Guenter Milde via Docutils-users wrote:
> Did you try list tables or CSV tables? Depending on your needs these 
> may facilitate your task a lot. 

I have not used them.

RST tables are powerful, and we are using some of those powerful 
features, so of course there will be problems. As we have hit problems 
we have figure them out continued. At the moment they are doing what we 
need.

One thing that was surprising was when we put Chinese characters in a 
table it broke. I traced through and saw it was an alignment issue, with 
wide east asian characters being considered twice as wide as ASCII.

-kb

Re: [Docutils-users] Docutils docs as a single HTML or PDF?

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

On 2019-09-01, Libor Jelinek wrote:
> Hello,
> before manually collecting all documents... How to read Docutils
> documentation as a single HTML or PDF that I will easily print, or save and
> read offline?

Unfortunately, there is no such meta file.

There were attempts to create a Sphinx version of the Docutils
documentation. This would provide for a cross-linked set of HTML
documents as well as a single PDF (via LaTeX). I don't know of a finished
such project, though.

Günter

Re: [Docutils-users] Writing Custom Directives, Expand Using Dynamic Data?

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

On 2019-09-01, Kent Borg wrote:

> So, since that previous e-mail, I went off and, with some help, did what 
> I described, and we are very close to declaring Phase I a victory. Phase 
> II will be putting this to practical work.

> Let me give you a report on how things have gone:

...

> Building tables programmatically with ASCII art---um, no, correction: 
> utf-8 art!---

?? https://sourceforge.net/p/docutils/feature-requests/6/

> is a bit ugly. 
> And building tables by creating the right 
> doctree nodes directly is not exactly well documented. At the moment we 
> are doing some of each and we will need to rationalize that.

Did you try list tables or CSV tables? Depending on your needs these may
facilitate your task a lot.

http://docutils.sourceforge.net/docs/ref/rst/directives.html#tables

Günter

Re: [Docutils-users] Writing Custom Directives, Expand Using Dynamic Data?

[Kent B. <ken...@bo...>]

Hey, I got an answer! I didn't see it until now--this list does not have 
much traffic...

So, since that previous e-mail, I went off and, with some help, did what 
I described, and we are very close to declaring Phase I a victory. Phase 
II will be putting this to practical work.

Let me give you a report on how things have gone:

  * First looked at sample code in the docutils tree for how to process
    RST data programmaticly, from inside another Python program, and the
    resulting code has worked with few ongoing changes needed.

  * Have written quite a few custom directives. I am usually not a fan
    of being too object oriented, but with inheritance patterns I set up
    it is possible for me to create new custom directive for a new
    dynamically generated table in just a few lines of code. Or for a
    new dynamically generated graphic in just a few lines of code.

  * Have done a couple custom roles for cases where we needed syntax
    that could occur without breaking off into a new paragraph.

  * Pending nodes are our friends! We can drop them in the doctree as we
    go, then traverse them later, giving each a chance to convert itself
    into appropriate static data.

  * The API going into this code is roughly three calls:

     1. Instantiate the thing, passing in the name of a starting RST
        file (in other words, initialize a context for everything else
        that happens);
     2. Make a call asking what dynamic data is needed, passing in an
        initially empty dictionary, get back a list of missing data,
        fetch what is missing, update the dictionary, call
        again...repeat until there is no more missing data;
     3. With the now-complete dictionary of dynamic data make a render
        call, listing the needed output format(s), and get back the
        results, make more render calls on the same context if desired.

    The code on the RST side is kept completely ignorant of where the
    dynamic data actually comes from, and the code doing the data fetch
    is kept completely ignorant of all details of what RST looks like or
    might mean. This was important, not necessarily obvious it was
    needed, and not trivial to do.

  * Not everything can be done as a pending node, some things need to
    happen at parse time.

    This was a problem! We aren't changing RST syntax, we mostly have no
    gripes with what the parser does and had no interest in rewriting or
    otherwise messing with it, but when the parser hits one of our
    custom directives or custom roles and that code immediately needs
    some external data, there is no provision to communicate those needs
    up the call chain. So we go around the call chain: We run the parser
    as its own thread and when our code needs to communicate with the
    outside world it does so over a pair of Python queues, one for
    communicating out what dynamic data is needed, the other for getting
    back in the requested stuff. When it has what it needs, it acts
    accordingly, and the parsing continues per normal until some other
    directive or role needs additional data at parse time. This is
    admittedly a hack, but I think a reasonable one.

The state machine code that implements the three-call API, initializes 
things, fires up the second thread, etc., is not simple, but its 
responsibilities are otherwise very limited, so it has been stable for 
some time, we don't need to mess with it much. That file is less than 
500-lines long, and that's with a lot of comments. Not bad.

Building tables programmatically with ASCII art---um, no, correction: 
utf-8 art!---is a bit ugly. And building tables by creating the right 
doctree nodes directly is not exactly well documented. At the moment we 
are doing some of each and we will need to rationalize that.

We have a couple custom directives that we don't use from our RST files 
at all, rather they are instantiated programmatically by custom roles, 
to set up pending operations.

It all works pretty well. We are at the point that we /can/ get the code 
to do what we want (sometimes after some exploring when we want 
something new), now we mostly have to make sure it /does/ do what we 
want. We are dealing with content issues now, which was the whole point.

The hardest parts were two:

 1. Figuring what custom directives and roles would accomplish what we
    needed while still being sensible RST. There was a risk of inventing
    a whole new, completely obscure, domain-specific, programming
    language here. I needed to avoid that. Our source documents need to
    be something that normal people who know how to write, can write.
 2. Segregating concerns wherever we could, and keeping the
    implementation as architecturally clean as possible. I have left out
    a lot here, there are other system concerns that had to be accounted
    for yet still chased away and not allowed to creep into and
    complexify this into never working.

It is hard to make something simple. I think we have done a pretty 
decent job.


-kb

[Docutils-users] Docutils docs as a single HTML or PDF?

[Libor J. <lje...@vi...>]

Hello,
before manually collecting all documents... How to read Docutils
documentation as a single HTML or PDF that I will easily print, or save and
read offline?

Libor

Re: [Docutils-users] 0.15.1.post1 packaging/versioning problem

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

post is (in my understanding) if no code changed.

so an upgrade from -0.15.1 to 0.15.1.post1 would not be necessary

to a system (e.g. pip) would not read the "post" word but only count parts
in the version
0.15.1 is the same as 0.15.1-post1 and both are smaller than 0.15.1.post1

whl-packages of version 0.15.1.post1 have to be changed
if the "-" ist used (0.15.1-post1) then the whl-file can be simply renamed.

then i will pack 0.15.2 soon

On Fri, 26 Jul 2019 at 13:02, Guenter Milde via Docutils-users <
doc...@li...> wrote:

> On 2019-07-25, Andrew Jaffe wrote:
>
> > Hi,
>
> > There’s a problem with the latest release version — even if you install
> > the `post1` version, it doesn’t register and still shows a need to
> > upgrade. Happens with `pip`/`pip2`/`pip3`.
>
>
> > ~$ pip list --outdated
> > Package  Version Latest       Type
> > -------- ------- ------------ -----
> > docutils 0.15.1  0.15.1.post1 sdist
>
> > ~$ pip install --upgrade docutils
> > Collecting docutils
> > Installing collected packages: docutils
> >   Found existing installation: docutils 0.15.1
> >     Uninstalling docutils-0.15.1:
> >       Successfully uninstalled docutils-0.15.1
> > Successfully installed docutils-0.15.1
>
> > ~$ pip list --outdated
> > Package  Version Latest       Type
> > -------- ------- ------------ -----
> > docutils 0.15.1  0.15.1.post1 sdist
>
> I suppose this is because the tar archive should have been named
> "docutils-0.15.1.tar.gz" instead of docutils-0.15.1-post1.tar.gz
> (the post1 is only for sub-sub micro releases).
>


> To fix the version issues and the test failures reported by Dmitry,
> I suggest a 0.15.2 release with
>
> * docutils-0.15.2.tar.gz
> * docutils-0.15.2-py2-none-any.whl
> * docutils-0.15.2-py3-none-any.whl
>
> (even if no change to 0.15 is required for py3).
>
> Günter
>
>
>
> _______________________________________________
> Docutils-users mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
>
> Please use "Reply All" to reply to the list.
>