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

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

Dear Kent,

On 2019-05-22, Kent Borg wrote:
> Hello,

> I am looking at using reStructuredText in the following custom way:

>   - Write documents using conventional rst for static data,

>   - And define my own custom directives and roles for dynamic data,

>   - Programmatically process my hybrid static/dynamic documents, 
> substituting/expanding my custom directives into static data,

>   - Likely write my own "writer"--or two or three--for custom output 
> formats, though that will come later.

> I don't see a lot of documentation on this kind of work. Looking about I 
> made it as far as core.publish_programmatically() and that looks 
> promising, plus the documentation there says that if I think I want to 
> use this code I should ask on the list first.

> So, two questions:

> 1) And I crazy?

Ambitious.

Docutils is designed with this use-case in mind, so it is not too hard to
achieve. However, there is no user manual for this task, so you will need
to read and understand the source code.


> 2) How should I go about this?

I suggest starting with a custom `front end tool`__ that imports and
enhances the parser prior to the call to publish_cmdline().

__ http://docutils.sourceforge.net/docs/api/cmdline-tool.html

An example for this approach is http://docutils.sourceforge.net/sandbox/jensj/latex_math/tools/rst2latexmath.py
from the times Docutils did not have native math support.


* Get a general understanding of rST and Docutils.

* Look for examples in the sandbox or other extensions__.

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


* Look for examples for directives and roles in docutils/parsers/rst/

* Eventually study examples for "transforms" (working on the generated
  document tree Python object) in docutils/transforms


Start with a simple example and come back to the list if there are
specific questions.

Good luck,

Günter