OK after reading Guenter's note I see my misunderstanding of this piece of code:

return [nodes.raw('', biblsthtml, format='html')]

but my question still stands.

As noted I had adapted it from another source; it seemed to do what I wanted. But I didn't really understand what it did. This mistake may have created some confusion around my underlying request for explanation and sample code.

From Guenter's reponse I now understand that this was more or less equivalent to using the raw directive in the reST source. Which in that manner -- ie raw directives in the rest source -- as Guenter noted could be adapted and targeted to the various other writers.

But my specific question remains.† If I have the custom directive

.. bibentries::
††† BCC+87;;

How do I write python code in the proper "Docutilic idiom" perhaps resembling my start with

class BibDirective(Directive):
††† has_content = True
††† def run(self):
directives.register_directive("bibentries", BibDirective)

which will allow me to translate the content to both html and latex.

So for purposes of explanation lets try for '<pre> This is the html bibdirective </pre>' to be emitted for html when I call

html_string = publish_string(\
††††††† source=content,\
††††††† writer_name='html',\
††††††† settings_overrides=htm_overrides)

and '\begin{verbatim} This is the latex bibdirective \end{verbatim}' to be emitted when I call:

latex_string = publish_string(\
††††††††††† source=content,\
††††††††††† writer_name='latex2e',\
††††††††††† settings_overrides=ltx_overrides)

Yes this is a dumb example but I think it is enough to get started. How can this question be made more simple or specific? Guenter is right in pointing out that the coding task is resembles coding the stock directives in the docutils source and in principle could begin there.†

But there is a lot of complexity in the docutils code base that is not relevant to my (or other "hacker/user) needs. That complexity makes it hard -- at least for me -- to use the docutils source as a basis for understanding how to "hack" extensions for personal use. In any case the starting point for my question is that I haven't been able to figure out how on my own to adapt the code in the docutils source for what I view as a modest extensions. (Donc J'affiche a la liste apres avoir passe quelques semaines a la recherche de cette question)

Responding with a simplified "toy" python example which would be my first preference.† That response might also be the basis for an "examples" addendum to the incomplete "Docutils Hackers Guide" And I not sure that I understand why there is so much resistance to just answering this question.†

If providing a "toy example" is not viewed as a legitimate request or is too burdensome, perhaps the list could at least identify specific pieces of code or one specific directive in the docutils source which would be most relevant for my needs and "easiest" to hack rather than just sending me back to the source in general.


PS Hoping that this can be posted to list in under 5 days!

On Mon, May 13, 2013 at 3:51 PM, Guenter Milde <milde@users.sf.net> wrote:
On 2013-05-13, Michael Prisant wrote:

> Thanks for this reply but I was looking for more specific advice with
> regard to coding rest custom directives (as opposed to using the "raw:
> approach) which are properly translated to both html and latex (like
> non-custom directives).

For specific adwise, we need a specific task. Otherwise, I could just
copy one of the standard directive classes (all of them are good examples
and (almost) all or them are properly translated to all output formats
that Docutils supports.

> Admittedly, I tried to pare my actual python code snippet to a bare
> minimum more or else working example. (This eliminated my actual bibtex
> processing which is what actually necessitated python code as opposed
> to just using "raw". †So some confusion seems to stem from the example
> given which doesn't do very much) On this basis I was hoping that one
> of the experienced coders could offer an *explicit* but *simple* python
> example to the group based on the very *simple* code snippets that I
> provided.

The problem I have with your example is, that it uses "raw" without any
need. I don't know for certain, but I don't think "raw" is required for
the real task either. Therefore, a solution to the stated problem of
providing two raw nodes -- one for latex one for html -- is just going
further in the wrong direction, away from a generic solution to the real
problem behind the example.


> The question here is really to help users who are attempting to code simple
> extensions to reST for their own specific uses as opposed to general
> development which would be folded into the software. †I want to translate a
> custom reST directive into just html and latex (as opposed to also
> translating into every possible output format) [2]

Did you already try to let the directive class return a list of "raw"
nodes (one for each supported output format)? AFAIK, "raw" nodes of the
"wrong" format are just ignored by the writers. Caveat: I did not test
this approach nor do I know whether it works this way.


AlienVault Unified Security Management (USM) platform delivers complete
security visibility with the essential security capabilities. Easily and
efficiently configure, manage, and operate all of your security controls
from a single console and one unified framework. Download a free trial.
Docutils-users mailing list

Please use "Reply All" to reply to the list.

Michael G. Prisant,