Remove URL quoting from refs before passing to Sphinx

Sphinx allows refs with spaces etc, and in fact autogenerates them with
the command [`autosectionlabel`][].

So if you put a:

```markdown
[Link 1](<some ref>)
[Link 2](<https://foo.com/bar baz>)
```

Then the links will be `some%20ref` and `https://foo.com/bar%20baz`.

We want to keep the URL quoting for external references, but if we're
passing it as `:any:` to Sphinx we need to unquote so Sphinx can find
the correct reference, the `<some ref>` should map to:

```rst
:ref:`some ref`
```

[`autosectionlabel`](https://www.sphinx-doc.org/en/master/usage/extensions/autosectionlabel.html)

Fixes: https://github.com/rtfd/recommonmark/issues/155

README.md

@@ -43,6 +43,41 @@ This allows you to write both `.md` and `.rst` files inside of the same project.
 
 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.
 
+#### Linking to headings in other files
+
+For linking to headings in other files you can use the [`autosectionlabel`][] sphinx feature, e.g.
+
+```python
+# conf.py
+
+extensions = [
+    # Auto-generate section labels.
+    'sphinx.ext.autosectionlabel',
+]
+
+# Prefix document path to section labels, otherwise autogenerated labels would look like 'heading'
+# rather than 'path/to/file:heading'
+autosectionlabel_prefix_document = True
+```
+
+You would use it like:
+
+```markdown
+<!-- path/to/file_1.md -->
+
+# Title
+
+## My Subtitle
+```
+
+```markdown
+<!-- file_2.md -->
+
+[My Subtitle][]
+
+[My Subtitle]: <path/to/file_1:My Subtitle>
+```
+
 ### AutoStructify
 
 AutoStructify makes it possible to write your documentation in Markdown, and automatically convert this
@@ -118,3 +153,4 @@ and is now maintained in the Read the Docs (rtfd) GitHub organization.
 [dc]: http://docutils.sourceforge.net/docs/ref/doctree.html
 [sphinx-issue]: https://bitbucket.org/birkenfeld/sphinx/issue/825/markdown-capable-sphinx
 [so-question]: http://stackoverflow.com/questions/2471804/using-sphinx-with-markdown-instead-of-rst
+[`autosectionlabel`]: https://www.sphinx-doc.org/en/master/usage/extensions/autosectionlabel.html

recommonmark/parser.py

@@ -11,9 +11,9 @@ from commonmark import Parser
 from warnings import warn
 
 if sys.version_info < (3, 0):
-    from urlparse import urlparse
+    from urlparse import urlparse, unquote
 else:
-    from urllib.parse import urlparse
+    from urllib.parse import urlparse, unquote
 
 __all__ = ['CommonMarkParser']
 
@@ -152,7 +152,7 @@ class CommonMarkParser(parsers.Parser):
         url_check = urlparse(destination)
         if not url_check.scheme and not url_check.fragment:
             wrap_node = addnodes.pending_xref(
-                reftarget=destination,
+                reftarget=unquote(destination),
                 reftype='any',
                 refdomain=None,  # Added to enable cross-linking
                 refexplicit=True,

tests/sphinx_xref/conf.py

@@ -3,6 +3,9 @@
 
 from recommonmark.parser import CommonMarkParser
 
+extensions = 'sphinx.ext.autosectionlabel']
+autosectionlabel_prefix_document = True
+
 templates_path = ['_templates']
 source_suffix = '.md'
 source_parsers = { '.md': CommonMarkParser }

tests/sphinx_xref/index.md

@@ -3,3 +3,7 @@ Header
 
 A paragraph [link](link) and [absolute link](/link). An [external link](http://www.google.com).
 
+A [ref with spaces][].
+
+
+[ref with spaces]: <link:Section 1>

tests/sphinx_xref/link.md

@@ -2,3 +2,7 @@ link
 ====
 
 The link file.
+
+## Section 1
+
+Autosectionlabel will generate a link for this heading at `link:Section 1`.