Sphinx - generate automatic references to Trac tickets and changesets

Question

Is Sphinx, is there way to automatically link text like #112 or r1023 to the corresponding tickets/changesets in Trac?

For eg:

#112  -> http://mytracsite/tickets/112
r1023 -> http://mytracsite/changeset/1023

See TracLinks for more examples.

Castlereagh

Answer 1

If you put this in your config.py

trac_url = 'http://mytratsite/'

from docutils import nodes, utils
from docutils.parsers.rst import roles
import urllib

def trac_role(role, rawtext, text, lineno, inliner, options={}, content=[]):
  ref = trac_url + '/intertrac/' + urllib.quote(text, safe='')
  node = nodes.reference(rawtext, utils.unescape(text), refuri=ref, **options)
  return [node],[]

roles.register_canonical_role('trac', trac_role)

Then you can use :trac:`#123` and :trac:`r1023` in your documents.

This is probably the easiest way to make quick links to a trac site. It automatically works for all kinds of TracLinks because it uses the intertrac mechanism for the links.

Rosner

Wow, adding roles is that easy? Cool! Only the register_canonical_role would look nicer as a @canonical_role decorator ;) – Earmark

You can also use the traclinks role from the repository of contributed Sphinx extensions: bitbucket.org/birkenfeld/sphinx-contrib/src – Arboriculture

Answer 2

Sphinx 1.0 now supports external links using the extlinks extension. Using a configurable role name (e.g. 'issue') you can write your links like:

:issue:`123`

and it will be converted to http://mytracsite/123.

Birkett