-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
Am 15.12.2010 21:41, schrieb Matthew Brett:
> 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.
Looks great! I tested it and the test/doc test worked fine once I had
simpleparse installed.
> 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...
Not at all. That is definitely one way. I see that one call is in a directive
function; there you could also call self.state.nested_parse(). But the other
being in the event handler, where no reST parser is available, I'd just keep
it that way.
> 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
Oh, indeed. Originally, missing-reference was designed for the intersphinx
extension, which doesn't need fromdocname since it returns an absolute URI
to another site.
I can fix this for 1.1 by adding more arguments to missing-reference, which
will be an incompatibility but a necessary one, since there aren't so many
uses for the missing-reference as it is now anyway.
> 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?
Unfortunately, this isn't perfectly correct either, since the fromdocname
isn't always the document in which the reference node occurs. This problem
occurs in builders that lump together nodes from multiple source files,
like the "singlehtml" builder.
> 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?
I've only recently refactored this code for Sphinx 1.1, and there the
warning shouldn't occur.
cheers,
Georg
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.16 (GNU/Linux)
iEYEARECAAYFAk0o9REACgkQN9GcIYhpnLAI2ACfdIBxJFrrm3m1jzM+F7ic6DcN
b9sAnjzQkBsx046PDGVimtRdE207iKf9
=y/ut
-----END PGP SIGNATURE-----
--
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.
