From: David G. <go...@py...> - 2008-02-28 00:43:13
Attachments:
signature.asc
|
Please don't post to both docutils-develop and -users. Choose one. [David Priest] > How does one know what parameters are required to insert a node into > an existing Doctree? Use the source, Luke! docutils/nodes.py contains all the node classes. The __init__ methods of the classes list the parameters, and there are lots of descriptive docstrings. docutils/parsers/rst/states.py is full of calls to nodes.* classes, as are the directives (docutils/parsers/rst/directives/*.py). Look for examples of the nodes you want to use. > For instance, after each section I want to programmatically insert a > link to the section. Why? > Experimenting with test rst, I've determined I > need to insert an nodes.image wrapped by a nodes.reference. Be sure to verify that the result is a valid doctree, that it fits docs/ref/docutils.dtd. docs/ref/doctree.txt may help with the interpretation. > While the resulting Doctree does appear to place the node xml > correctly, I've yet to figure out how to determine what to pass to the > node class. > > def addEditLinks(doctree): > for section in doctree.traverse(condition=nodes.section): > reference = nodes.reference( > '', > 'Edit Section', > refid=section['ids'][0], > ) > image = nodes.image( > [ magic?! needs image uri] So supply it. No magic. docutils.dtd tells you that an image element requires a "uri" attribute. nodes.py tells you that "class image" is a "General, Inline, Element" subclass. The first two are merely classifiers. The signature of the Element class is "(self, rawsource='', *children, **attributes)". No children, "uri" is an attribute. So: image = nodes.image(raw_source, uri='http://example.org/image.png') image = nodes.image(raw_source, uri='relative/path/image.png') You can even omit the raw_source parameter, since there's a default (''). > ) > reference += image > section.insert(0, reference) Why are you inserting the reference at the beginning of the section? That would result in an invalid doctree. The section title must be first. From docutils.dtd: <!ELEMENT section (title, subtitle?, info?, decoration?, %structure.model;)> A reference can be a body element, which is part of structure.model, so it must come after any title, subtitle, info, or decoration element. > return doctree > > The above code semi-works: it inserts things into the right place, and > the resulting doctree looks pretty close to correct, but html4css1 > barfs because I'm not passing the correct variables correctly. Probably because you're passing an invalid doctree. A document is a well-defined data structure, and all Docutils doctrees must conform to the rules. docutils.dtd is an expression of those rules. > I suspect Docutils is performing meta-programming magic (factories?) > to create the nodes. That boggles my mind, but I can cope with it... There is no meta-programming in Docutils. There is some dynamic stuff in there though. > *if I only knew how to figure out what to pass*. Again: Use the source, Luke! -- David Goodger <http://python.net/~goodger> |
From: David G. <go...@py...> - 2008-02-29 02:47:55
Attachments:
signature.asc
|
[David Priest] > Ahhh! I did not realize the Doctree->HTML conversion would be > checking that the rst->Doctree conversion was done correctly. Sly! The doctree isn't explicitly checked for validity, only implicitly. All downstream code expects valid doctrees, and invalid doctrees will often cause exceptions. -- David Goodger <http://python.net/~goodger> |