User discussion for the docutils project.

Angel Yanguas-Gil | 30 Apr 2012 06:45

how to incorporate a new role into distutils

Hi,

I have been playing with docutils and I have created a new role
:chem:, to process subscripts and superscripts for chemical formula
(i.e. :chem: or :ch:`Al2O3` == Al<sub>2</sub>O<sub>3</sub>).

It worked, and now I have it running in my local copy. However, I
still have a couple of questions:

1) So far I have included it in my local copy of roles.py. Is there
any other way of loading custom roles / add-ons to distutils that does
not involve modifying roles.py? (like a local directory where custom
roles could be added/imported into distutils?).
2) Is nodes.Text the standard way of returning a text node?
3) Can roles be made to work recursively? In other words, am I missing
a simple way of calling a role within a role (i.e. so that I can
expand Al2O3 into "Al :subs:`2`\ O:subs:`3`\ " and that magically
everything is taken care of)?.
4) Is a role the best way of doing this? Should I be using a directive
instead, or is it an overkill?

Many thanks,

ay

------------------------------------------------------------------------------
Live Security Virtual Conference
Exclusive live event will cover all the ways today's security and 
threat landscape has changed and how IT managers can respond. Discussions 
will include endpoint security, mobile security and the latest in malware

(Continue reading)

headers

Guenter Milde | 4 May 2012 09:56

Re: how to incorporate a new role into distutils

On 2012-04-30, Angel Yanguas-Gil wrote:
> Hi,

> I have been playing with docutils and I have created a new role
>:chem:, to process subscripts and superscripts for chemical formula
> (i.e. :chem: or :ch:`Al2O3` == Al<sub>2</sub>O<sub>3</sub>).

Looks interesting.

> It worked, and now I have it running in my local copy. However, I
> still have a couple of questions:

> 1) So far I have included it in my local copy of roles.py. Is there
> any other way of loading custom roles / add-ons to distutils that does
> not involve modifying roles.py? (like a local directory where custom
> roles could be added/imported into distutils?).

There is currently no plug-in mechanism in Docutils and no clear plan how to
implement one in a clean and secure manner.

The usual practice is to use a custom front-end, load Docutils and
customize it before calling the publisher functions. See the sandbox for
examples of this approach (e.g. the now obsolete
sandbox/code-block-directive/rst2html-highlight.py). 

Adding directives this way is documented: there is a "register directive" API.
For roles, I see ``register_canonical_role(name, role_fn)`` in roles.py.

The downside is that this approach does not scale well:

(Continue reading)

headers

Angel Yanguas-Gil | 9 May 2012 19:06

Re: how to incorporate a new role into distutils

Thanks for your input. Nesting the nodes in an inline node is a good
idea, so far I was returning them as a list, but an inline node is a
more elegant solution. I will definitely check out the sandbox for
front-end customization.

Angel

On Fri, May 4, 2012 at 2:56 AM, Guenter Milde <milde <at> users.sf.net> wrote:
> On 2012-04-30, Angel Yanguas-Gil wrote:
>> Hi,
>
>> I have been playing with docutils and I have created a new role
>>:chem:, to process subscripts and superscripts for chemical formula
>> (i.e. :chem: or :ch:`Al2O3` == Al<sub>2</sub>O<sub>3</sub>).
>
> Looks interesting.
>
>> It worked, and now I have it running in my local copy. However, I
>> still have a couple of questions:
>
>> 1) So far I have included it in my local copy of roles.py. Is there
>> any other way of loading custom roles / add-ons to distutils that does
>> not involve modifying roles.py? (like a local directory where custom
>> roles could be added/imported into distutils?).
>
> There is currently no plug-in mechanism in Docutils and no clear plan how to
> implement one in a clean and secure manner.
>
> The usual practice is to use a custom front-end, load Docutils and
> customize it before calling the publisher functions. See the sandbox for

(Continue reading)