Merge pull request #61 from pfultz2/pending-xref

Use pending_xref for links

README.md

@@ -34,6 +34,10 @@ source_suffix = ['.rst', '.md']
 
 This allows you to write both `.md` and `.rst` files inside of the same project.
 
+### Links
+
+For all links in commonmark that aren't explicit URLs, they are treated as cross references with the [`:any:`](http://www.sphinx-doc.org/en/stable/markup/inline.html#role-any) role. This allows referencing a lot of things including files, labels, and even objects in the loaded domain.
+
 ### AutoStructify
 
 To use the advanced markdown to rst transformations you must add `AutoStructify` to your Sphinx conf.py.

recommonmark/parser.py

@@ -1,5 +1,6 @@
 from contextlib import contextmanager
 import itertools
+import sphinx
 
 from docutils import parsers, nodes
 
@@ -226,17 +227,35 @@ def inline_entity(inline):
     entity_node = nodes.paragraph('', val, format='html')
     return entity_node
 
+# The goal is to make references work like the `:any:` role except when an url
+# is given. See the XRefRole class in sphinx:
+# https://github.com/sphinx-doc/sphinx/blob/master/sphinx/roles.py
+
+
+def make_refnode(label, target, has_explicit_title):
+    if target and target.startswith(('http://', 'https://')):
+        ref_node = nodes.reference()
+        ref_node['name'] = label
+        ref_node['refuri'] = target
+        return ref_node
+    xref_node = sphinx.addnodes.pending_xref(
+        label,
+        reftype='any',
+        refexplicit=has_explicit_title,
+        refwarn=True)
+    if target:
+        xref_node['reftarget'] = target
+    else:
+        xref_node['refname'] = label
+    return xref_node
+
 
 def reference(block):
-    ref_node = nodes.reference()
 
     label = make_refname(block.label)
 
-    ref_node['name'] = label
-    if block.destination is not None:
-        ref_node['refuri'] = block.destination
-    else:
-        ref_node['refname'] = label
+    has_explicit_title = True if block.title else False
+    ref_node = make_refnode(label, block.destination, has_explicit_title)
 
     if block.title:
         ref_node['title'] = block.title

requirements.txt

@@ -1,4 +1,4 @@
 commonmark<=0.5.4
 docutils>=0.11
-sphinx>=1.3.1
+sphinx>=1.5
 pytest==2.7.2

tests/sphinx_xref/conf.py

@@ -0,0 +1,22 @@
+
+# -*- coding: utf-8 -*-
+
+from recommonmark.parser import CommonMarkParser
+
+templates_path = ['_templates']
+source_suffix = '.md'
+source_parsers = { '.md': CommonMarkParser }
+master_doc = 'index'
+project = u'sphinxproj'
+copyright = u'2015, rtfd'
+author = u'rtfd'
+version = '0.1'
+release = '0.1'
+highlight_language = 'python'
+language = None
+exclude_patterns = ['_build']
+pygments_style = 'sphinx'
+todo_include_todos = False
+html_theme = 'alabaster'
+html_static_path = ['_static']
+htmlhelp_basename = 'sphinxproj'

tests/sphinx_xref/index.md

@@ -0,0 +1,5 @@
+Header
+======
+
+A paragraph [link](link) and [absolute link](/link). An [external link](http://www.google.com).
+

tests/sphinx_xref/link.md

@@ -0,0 +1,4 @@
+link
+====
+
+The link file.

tests/test_sphinx.py

@@ -9,7 +9,7 @@
 
 class SphinxIntegrationTests(unittest.TestCase):
 
-    def _run_test(self, test_dir, test_file, test_string):
+    def _run_test(self, test_dir, test_file, test_strings):
         os.chdir('tests/{0}'.format(test_dir))
         try:
             app = Sphinx(
@@ -23,7 +23,8 @@ def _run_test(self, test_dir, test_file, test_string):
             app.build(force_all=True)
             with io.open(test_file, encoding='utf-8') as fin:
                 text = fin.read().strip()
-                self.assertIn(test_string, text)
+                for test_string in test_strings:
+                    self.assertIn(test_string, text)
         finally:
             shutil.rmtree('_build')
             os.chdir('../..')
@@ -34,7 +35,7 @@ def test_integration(self):
         self._run_test(
             'sphinx_code_block',
             '_build/text/index.html',
-            '<div class="highlight">'
+            ['<div class="highlight">']
         )
 
 
@@ -44,7 +45,7 @@ def test_integration(self):
         self._run_test(
             'sphinx_indented_code',
             '_build/text/index.html',
-            '<div class="highlight">'
+            ['<div class="highlight">']
         )
 
 class NestedHeaderBlock(SphinxIntegrationTests):
@@ -62,5 +63,14 @@ def test_integration(self):
         self._run_test(
             'sphinx_custom_md',
             '_build/text/index.html',
-            '</table>'
+            ['</table>']
+        )
+
+class XrefTests(SphinxIntegrationTests):
+
+    def test_integration(self):
+        self._run_test(
+            'sphinx_xref',
+            '_build/text/index.html',
+            ['href="link.html"', 'href="http://www.google.com"']
         )