Make extlinks more flexible: use string substitution to build the full URL.

doc/conf.py

@@ -9,8 +9,6 @@ import sys, os, re
 extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo',
               'sphinx.ext.autosummary']
 
-extlinks = {'issue': ('http://bugs.python.org/issue', 'issue ')}
-
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 

doc/ext/extlinks.rst

@@ -27,11 +27,13 @@ The extension adds one new config value:
    short alias names to a base URL and a *prefix*.  For example, to create an
    alias for the above mentioned issues, you would add ::
 
-      extlinks = {'issue': ('http://bitbucket.org/birkenfeld/sphinx/issue/',
+      extlinks = {'issue': ('http://bitbucket.org/birkenfeld/sphinx/issue/%s',
                             'issue ')}
 
    Now, you can use the alias name as a new role, e.g. ``:issue:`123```.  This
    then inserts a link to http://bitbucket.org/birkenfeld/sphinx/issue/123.
+   As you can see, the target given in the role is substituted in the base URL
+   in the place of ``%s``.
 
    The link *caption* depends on the second item in the tuple, the *prefix*:
 

sphinx/ext/extlinks.py

@@ -8,10 +8,10 @@
 
     This adds a new config value called ``extlinks`` that is created like this::
 
-       extlinks = {'exmpl': ('http://example.com/', prefix), ...}
+       extlinks = {'exmpl': ('http://example.com/%s.html', prefix), ...}
 
     Now you can use e.g. :exmpl:`foo` in your documents.  This will create a
-    link to ``http://example.com/foo``.  The link caption depends on the
+    link to ``http://example.com/foo.html``.  The link caption depends on the
     *prefix* value given:
 
     - If it is ``None``, the caption will be the full URL.
@@ -32,15 +32,20 @@ from sphinx.util import split_explicit_title
 def make_link_role(base_url, prefix):
     def role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
         text = utils.unescape(text)
-        has_explicit_title, title, url = split_explicit_title(text)
-        # NOTE: not using urlparse.urljoin() here, to allow something like
-        # base_url = 'bugs.python.org/issue'  and  url = '1024'
-        full_url = base_url + url
+        has_explicit_title, title, part = split_explicit_title(text)
+        try:
+            full_url = base_url % part
+        except (TypeError, ValueError):
+            env = inliner.document.settings.env
+            env.warn(env.docname, 'unable to expand %s extlink with base '
+                     'URL %r, please make sure the base contains \'%%s\' '
+                     'exactly once' % (typ, base_url))
+            full_url = base_url + part
         if not has_explicit_title:
             if prefix is None:
                 title = full_url
             else:
-                title = prefix + url
+                title = prefix + part
         pnode = nodes.reference(title, title, refuri=full_url)
         return [pnode], []
     return role

tests/root/conf.py

@@ -6,7 +6,7 @@ sys.path.append(os.path.abspath('.'))
 
 extensions = ['ext', 'sphinx.ext.autodoc', 'sphinx.ext.jsmath',
               'sphinx.ext.coverage', 'sphinx.ext.todo',
-              'sphinx.ext.autosummary']
+              'sphinx.ext.autosummary', 'sphinx.ext.extlinks']
 
 jsmath_path = 'dummy.js'
 
@@ -16,7 +16,7 @@ master_doc = 'contents'
 source_suffix = '.txt'
 
 project = 'Sphinx <Tests>'
-copyright = '2008, Georg Brandl & Team'
+copyright = '2010, Georg Brandl & Team'
 # If this is changed, remember to update the versionchanges!
 version = '0.6'
 release = '0.6alpha1'
@@ -53,6 +53,9 @@ coverage_c_regexes = {'cfunction': r'^PyAPI_FUNC\(.*\)\s+([^_][\w_]+)'}
 
 autosummary_generate = ['autosummary']
 
+extlinks = {'issue': ('http://bugs.python.org/issue%s', 'issue '),
+            'pyurl': ('http://python.org/%s', None)}
+
 # modify tags from conf.py
 tags.add('confpytag')
 

tests/root/contents.txt

@@ -22,6 +22,7 @@ Contents:
    autodoc
    autosummary
    metadata
+   extensions
 
    Python <http://python.org/>
 

tests/root/extensions.txt

@@ -0,0 +1,8 @@
+Test for diverse extensions
+===========================
+
+extlinks
+--------
+
+Test diverse links: :issue:`1000` and :pyurl:`dev/`, also with
+:issue:`explicit caption <1042>`.

tests/test_build.py

@@ -121,6 +121,11 @@ HTML_XPATH = {
     'bom.html': {
         ".//title": " File with UTF-8 BOM",
     },
+    'extensions.html': {
+        ".//a[@href='http://python.org/dev/']": "http://python.org/dev/",
+        ".//a[@href='http://bugs.python.org/issue1000']": "issue 1000",
+        ".//a[@href='http://bugs.python.org/issue1042']": "explicit caption",
+    },
     '_static/statictmpl.html': {
         ".//project": 'Sphinx <Tests>',
     },