Hi, I've been working for a few days on my first sphinx extension, an attempt to allow us to include citations from bibtex files.
I wanted to ask for feedback about the design. In particular I hit a couple of things that I wasn't sure about that I'd like advice on. The extension is here: https://github.com/matthew-brett/bibstuff/tree/master/sphinxext and the code in particular is in the bibref.py file in that directory. It's built on top of the bibstuff code by Dylan Schwilk and Alan Isaac: http://pricklysoft.org/software/bibstuff.html. I had to modify their code a little to get the extension to work, so the extension is inside a modified copy of their code: https://github.com/matthew-brett/bibstuff >From the bibstuff.py file docstring: Implements two new directives:: .. biblisted:: myrefs.bib :style: default ref1 ref2 ref3 which results in the generation of 3 citation targets with the references extracted from myrefs.bib and formatted according to the `default` style. .. bibmissing:: myrefs.bib :style: default This directive takes no content, and watches for missing citations during the build. If it has a citation for the missing reference, it inserts the citation during build. I'd be very grateful for feedback. I had two questions. The first is: I wanted to insert new rst formatted code into the doctree, and the way I did this, was put the code into a new in-memory document, and pull the parsed nodes out of that, as in this function: def rst2nodes(text, settings): new_doc = new_document('temp-string', settings) parser = Parser() parser.parse(text, new_doc) return new_doc.children Is that the right way to do that task? Sorry if that's an ignorant question... Second question: for obvious reasons I found I wanted to handle the missing-reference event, but the event parameters weren't enough to do what I wanted. Specifically, what I needed to do with the missing reference was (from sphinx/environment.py around 1343): newnode = make_refnode(builder, fromdocname, docname, labelid, contnode) but, the missing-reference event only gives me:: missing-reference(app, env, node, contnode) I can get the builder, and docname and labelid, and I've been passed the contnode, but there does not appear to be a way to get the 'fromdocname' that I needed. I think that's the same as for this post: http://www.mail-archive.com/sphinx-dev@googlegroups.com/msg01895.html In the end I resorted to this - hack: def doctree_read(app, doctree): """ Give each pending citation its docname """ for pref in doctree.traverse(addnodes.pending_xref): if pref['reftype'] != 'citation': continue pref['docname'] = app.env.docname I wanted ask whether there is a better way to do this? Lastly, I noticed that the code still raises a warning that it didn't find my citations, even when the missing-reference event returned a citation, because of the code around 1340 in environment.py in my version. Would you be interested in a patch to defer this warning until after checking the missing-reference? Thanks a lot for any help or feedback, Best, Matthew -- You received this message because you are subscribed to the Google Groups "sphinx-dev" group. To post to this group, send email to sphinx-...@googlegroups.com. To unsubscribe from this group, send email to sphinx-dev+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en.
