Extend RST to support additional directive types

[anatoly techtonik <techtonik@…>]

When Trac shows WikiRestructuredText page from Sphinx for example it shows a lot of "Unknown directive type" errors - ​http://www.google.com/search?q=trac+Unknown+directive+type

It would be nice if installed Sphinx (and other packages) could provide these directives for Trac.

[Christian Boos]

I'm not sure if "running" those directives in isolation would make sense… what do you think a .. currentmodule: blah directive should do?

OTOH, showing big scary red boxes for such missing directives is indeed very annoying, but this has already been taken care of in trunk (r10358). See e.g. source:trunk/doc/api/trac_env.rst​.

"worksforme"?

[anatoly techtonik <techtonik@…>]

The target page seem much better. But..

It would be nice to see at least Sphinx integration. For example, cross-link functions referenced in the same page. Perhaps these question marks popups could link to documentation how to provide Macros/Extensions to make those unknown items familiar to Trac. Then Sphinx project (or smb. else) could release an extension at least. Is that possible in current state?

[Christian Boos]

The trac.mimeview.rst.ReStructuredTextRenderer.render() method could take care of saving the current Trac environment and rendering context somewhere in the docutils inputs and this could allow plugins to register docutils directives and roles that could make a safe use of Trac's API by retrieving these informations.

Now that I'm staring at the code… I see that we currently register the trac directive and role each time in render(), the component (self) and context being free variables there, picked from the render() method, and this is completely thread-unsafe.

The trac directive and role should be registered once, and should retrieve the env and context through the docutils inputs, like proposed above. This input should probably be a custom Inliner, as this will be available from both the role (directly) and the directive (through state_machine.inliner).

Finally, the trac role should be a "canonical" one even, no need to localize the "trac" name.

[Christian Boos]

rst: don't store Trac env and context in the directive and role handlers.

[Christian Boos]

9915-register-once-r10420.diff​ implements the approach described in comment:3 (except that inliner should be retrieved from the state instead of the state_machine, as I misread the docutils code).

[anatoly techtonik <techtonik@…>]

Unfortunately I am not the one who is able to review this diff, but I am glad it is given a go. Perhaps I need more time or an example plugin to see how it works.

[Christian Boos]

One thing I didn't test is the compatibility with older docutils (tested 0.7). We still have "docutils≥0.3" as the requirement in setup.py, not sure if Trac still works with 0.3 though (the TracInstall page even says docutils version ≥ 0.3.9).

[Christian Boos]

I've tested the patch (+ minor modifications) with docutils 0.3.9, 0.4, 0.5, 0.6 and 0.7. Everything seems to work fine. Applied in r10458.

[Ryan J Ollos]

Replying to cboos:

One thing I didn't test is the compatibility with older docutils (tested 0.7). We still have "docutils≥0.3" as the requirement in setup.py, not sure if Trac still works with 0.3 though (the TracInstall page even says docutils version ≥ 0.3.9).

docutils version requirement in setup.py set to 0.3.9 in [13081:13083] (comment:7:ticket:11694).