Merge pull request #1 from readthedocs/master

sync

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

docs/auto_structify.md

@@ -38,13 +38,13 @@ One of important command in tools like sphinx is `toctree`. This is a command to
 tell sphinx about the structure of the documents. In markdown, usually we manually list of contents by a bullet list
 of url reference to the other documents.
 
-AutoStructify will transforms bullet list of document URLs
+AutoStructify transforms bullet list of document URLs like this
 
 ```
 * [Title1](doc1.md)
 * [Title2](doc2.md)
 ```
-will be translated to the AST of following reStructuredText code
+to the AST of this following reStructuredText code
 ```rst
 .. toctree::
    :maxdepth: 1

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,
@@ -178,8 +178,15 @@ class CommonMarkParser(parsers.Parser):
         img_node = nodes.image()
         img_node['uri'] = mdnode.destination
 
-        if mdnode.title:
-            img_node['alt'] = mdnode.title
+        if mdnode.first_child and mdnode.first_child.literal:
+            content = [mdnode.first_child.literal]
+            n = mdnode.first_child
+            mdnode.first_child.literal = ''
+            mdnode.first_child = mdnode.last_child = None
+            while getattr(n, 'nxt'):
+                n.nxt, n = None, n.nxt
+                content.append(n.literal)
+            img_node['alt'] = ''.join(content)
 
         self.current_node.append(img_node)
         self.current_node = img_node

tests/sphinx_generic/index.md

@@ -23,7 +23,7 @@ Foo
 
 Bar
 
-![foo](/image.png "Example")
+![foo "handle quotes"](/image.png "Example")
 
     #!/bin/sh
     python

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`.

tests/test_basic.py

@@ -226,13 +226,13 @@ class TestParsing(unittest.TestCase):
     def test_image(self):
         self.assertParses(
             """
-            ![foo](/url "title")
+            ![foo "handle quotes"](/url "title")
             """,
             """
             <?xml version="1.0" ?>
             <document source="&lt;string&gt;">
               <paragraph>
-                <image alt="title" uri="/url">foo</image>
+                <image alt="foo &quot;handle quotes&quot;" uri="/url"></image>
               </paragraph>
             </document>
             """

tests/test_sphinx.py

@@ -129,7 +129,7 @@ class GenericTests(SphinxIntegrationTests):
     def test_image(self):
         output = self.read_file('index.html')
         self.assertIn(
-            '<p><img alt="Example" src="image.png" />foo</p>',
+            '<p><img alt="foo &quot;handle quotes&quot;" src="image.png" /></p>',
             output
         )