Rewrite local links for RST (and other source) files, too

Author: mgeier

doc/a-normal-rst-file.rst

@@ -5,21 +5,122 @@ This is a normal RST file.
 
 .. note:: Those still work!
 
-Links to Notebooks
-------------------
+Links to Notebooks (and Other Sphinx Source Files)
+--------------------------------------------------
 
-Links to notebooks can be easily created:
-:ref:`/subdir/a-notebook-in-a-subdir.ipynb`
-(the notebook title is used as link text).
-You can also use
-:ref:`an alternative text </subdir/a-notebook-in-a-subdir.ipynb>`.
+Links to Sphinx source files can be created like normal `Sphinx hyperlinks`_,
+just using a relative path to the local file: link_.
 
-The above links were created with:
+.. _Sphinx hyperlinks: http://www.sphinx-doc.org/en/stable/rest.html
+                       #external-links
+.. _link: subdir/a-notebook-in-a-subdir.ipynb
+
+.. code-block:: rst
+
+    using a relative path to the local file: link_.
+
+    .. _link: subdir/a-notebook-in-a-subdir.ipynb
+
+If the link text has a space (or some other strange character) in it, you have
+to surround it with backticks: `a notebook link`_.
+
+.. _a notebook link: subdir/a-notebook-in-a-subdir.ipynb
+
+.. code-block:: rst
+
+    surround it with backticks: `a notebook link`_.
+
+    .. _a notebook link: subdir/a-notebook-in-a-subdir.ipynb
+
+You can also use an `anonymous hyperlink target`_, like this: link__.
+If you have multiple of those, their order matters!
+
+.. _anonymous hyperlink target: http://docutils.sourceforge.net/docs/ref/rst/
+                                restructuredtext.html#anonymous-hyperlinks
+
+__ subdir/a-notebook-in-a-subdir.ipynb
+
+.. code-block:: rst
+
+    like this: link__.
+
+    __ subdir/a-notebook-in-a-subdir.ipynb
+
+Finally, you can use `Embedded URIs`_, like this
+`link <subdir/a-notebook-in-a-subdir.ipynb>`_.
+
+.. _Embedded URIs: http://docutils.sourceforge.net/docs/ref/rst/
+                   restructuredtext.html#embedded-uris-and-aliases
+
+.. code-block:: rst
+
+    like this `link <subdir/a-notebook-in-a-subdir.ipynb>`_.
+
+.. note::
+
+    These links should also work on Github and in other rendered
+    reStructuredText pages.
+
+Links to subsections are also possible by adding a hash sign (``#``) and the
+section title to any of the above-mentioned link variants.
+You have to replace spaces in the section titles by hyphens.
+For example, see this subsection_.
+
+.. _subsection: subdir/a-notebook-in-a-subdir.ipynb#A-Sub-Section
+
+.. code-block:: rst
+
+    For example, see this subsection_.
+
+    .. _subsection: subdir/a-notebook-in-a-subdir.ipynb#A-Sub-Section
+
+
+Links to Local Files (HTML only)
+--------------------------------
+
+If you use any of the above-mentioned methods to link to a local file that
+*isn't* a Sphinx source file, it will be automatically copied to the HTML output
+directory, like it would if you `link from a notebook`__.
+
+Alternatively, you can of course as always use Sphinx's download__ role.
+
+__ markdown-cells.ipynb#Links-to-Local-Files-(HTML-only)
+__ http://www.sphinx-doc.org/en/stable/markup/inline.html#role-download
+
+
+Links to Notebooks, Ye Olde Way
+-------------------------------
+
+In addition to the way shown above, you can also create links to notebooks (and
+other Sphinx source files) with
+`:ref: <http://www.sphinx-doc.org/en/stable/markup/inline.html#role-ref>`_.
+This has some disadvantages:
+
+* It is arguably a bit more clunky.
+* Because ``:ref:`` is a Sphinx feature, the links don't work on Github and
+  other rendered reStructuredText pages that use plain old ``docutils``.
+
+It also has one important advantage:
+
+* The link text can automatically be taken from the actual section title.
+
+A link with automatic title looks like this:
+:ref:`/subdir/a-notebook-in-a-subdir.ipynb`.
 
 .. code-block:: rst
 
     :ref:`/subdir/a-notebook-in-a-subdir.ipynb`
-    :ref:`an alternative text </subdir/a-notebook-in-a-subdir.ipynb>`
+
+But you can also provide
+:ref:`your own link title </subdir/a-notebook-in-a-subdir.ipynb>`.
+
+.. code-block:: rst
+
+    :ref:`your own link title </subdir/a-notebook-in-a-subdir.ipynb>`
+
+However, if you want to use your own title, you are probably better off using
+the method described above in
+`Links to Notebooks (and Other Sphinx Source Files)`_.
 
 Links to subsections are also possible, e.g.
 :ref:`/subdir/a-notebook-in-a-subdir.ipynb#A-Sub-Section`
@@ -35,9 +136,9 @@ These links were created with:
 
 .. note::
 
+    * The paths have to be relative to the top source directory and they have to
+      start with a slash (``/``).
     * Spaces in the section title have to be replaced by hyphens!
-    * Notebook paths have to be relative to the top source directory and they
-      have to start with a slash (``/``).
 
 Sphinx Directives for Info/Warning Boxes
 ----------------------------------------

doc/orphan.ipynb

@@ -23,16 +23,10 @@
     "    [some link text](notebookname.ipynb)\n",
     "    ```\n",
     "\n",
-    "* ... from a [reST page](a-normal-rst-file.rst#Links-to-Notebooks) using\n",
+    "* ... from a [reST page](a-normal-rst-file.rst#links-to-notebooks-and-other-sphinx-source-files) using\n",
     "\n",
     "    ```rst\n",
-    "    :ref:`/notebookname.ipynb`\n",
-    "    ```\n",
-    "\n",
-    "    or\n",
-    "\n",
-    "    ```rst\n",
-    "    :ref:`alternative link text </notebookname.ipynb>`\n",
+    "    `some link text <notebookname.ipynb>`_\n",
     "    ```\n",
     "\n",
     "Sphinx raises a warning in case of orphaned documents:\n",

src/nbsphinx.py

@@ -616,7 +616,9 @@ class NotebookParser(rst.Parser):
     def get_transforms(self):
         """List of transforms for documents parsed by this parser."""
         return rst.Parser.get_transforms(self) + [
-            ProcessLocalLinks, ReplaceAlertDivs]
+            CreateNotebookSectionAnchors,
+            ReplaceAlertDivs,
+        ]
 
     def parse(self, inputstring, document):
         """Parse *inputstring*, write results to *document*.
@@ -1005,12 +1007,12 @@ class ProcessLocalLinks(docutils.transforms.Transform):
     """Process links to local files.
 
     Marks local files to be copied to the HTML output directory and
-    turns links to local notebooks into ``:doc:``/``:ref:`` links.
+    turns links to source files into ``:doc:``/``:ref:`` links.
 
     Links to subsections are possible with ``...#Subsection-Title``.
     These links use the labels created by CreateSectionLabels.
 
-    Links to subsections use ``:ref:``, links to whole notebooks use
+    Links to subsections use ``:ref:``, links to whole source files use
     ``:doc:``.  Latter can be useful if you have an ``index.rst`` but
     also want a distinct ``index.ipynb`` for use with Jupyter.
     In this case you can use such a link in a notebook::
@@ -1023,24 +1025,37 @@ class ProcessLocalLinks(docutils.transforms.Transform):
 
     """
 
-    default_priority = 400  # Should probably be adjusted?
+    default_priority = 500  # After AnonymousHyperlinks (440)
 
     _subsection_re = re.compile(r'^([^#]+)((\.[^#]+)#.+)$')
 
     def apply(self):
         env = self.document.settings.env
         for node in self.document.traverse(docutils.nodes.reference):
-            uri = node.get('refuri', '')
-            if not uri:
-                continue  # No URI (e.g. named reference)
-            elif '://' in uri:
+            # NB: Anonymous hyperlinks must be already resolved at this point!
+            refuri = node.get('refuri')
+            if not refuri:
+                refname = node.get('refname')
+                if refname:
+                    refid = self.document.nameids.get(refname)
+                else:
+                    # NB: This can happen for anonymous hyperlinks
+                    refid = node.get('refid')
+                target = self.document.ids.get(refid)
+                if not target:
+                    continue  # No corresponding target, Sphinx may warn later
+                refuri = target.get('refuri')
+                if not refuri:
+                    continue  # Target doesn't have URI
+
+            if '://' in refuri:
                 continue  # Not a local link
-            elif uri.startswith('#') or uri.startswith('mailto:'):
+            elif refuri.startswith('#') or refuri.startswith('mailto:'):
                 continue  # Nothing to be done
 
             # NB: We look for "fragment identifier" before unquoting
-            fragment = self._subsection_re.match(uri)
-            uri = unquote(uri)
+            fragment = self._subsection_re.match(refuri)
+            refuri = unquote(refuri)
             for suffix in env.config.source_suffix:
                 if fragment:
                     if fragment.group(3).lower() == suffix.lower():
@@ -1051,17 +1066,17 @@ def apply(self):
                         refdomain = 'std'
                         break
                 else:
-                    if uri.lower().endswith(suffix.lower()):
-                        target = uri[:-len(suffix)]
+                    if refuri.lower().endswith(suffix.lower()):
+                        target = refuri[:-len(suffix)]
                         target_ext = ''
                         reftype = 'doc'
                         refdomain = None
                         break
             else:
                 if fragment:
-                    uri = unquote(fragment.group(1)) + fragment.group(3)
+                    refuri = unquote(fragment.group(1)) + fragment.group(3)
                 file = os.path.normpath(
-                    os.path.join(os.path.dirname(env.docname), uri))
+                    os.path.join(os.path.dirname(env.docname), refuri))
                 if not os.path.isfile(os.path.join(env.srcdir, file)):
                     env.app.warn('file not found: {!r}'.format(file),
                                  env.doc2path(env.docname))
@@ -1089,15 +1104,28 @@ def apply(self):
                 node.replace_self(xref)
 
 
-class CreateSectionLabels(docutils.transforms.Transform):
-    """Make labels for each document parsed by Sphinx, each section thereof,
-    and each Sphinx domain object.
-
-    These labels are referenced in ProcessLocalLinks.
+class CreateNotebookSectionAnchors(docutils.transforms.Transform):
+    """Create section anchors for Jupyter notebooks.
 
     Note: Sphinx lower-cases the HTML section IDs, Jupyter doesn't.
-    This transform creates labels in the Jupyter style for Jupyter
-    notebooks, but keeps the Sphinx style for all other source files.
+    This transform creates anchors in the Jupyter style.
+
+    """
+
+    default_priority = 200  # Before CreateSectionLabels (250)
+
+    def apply(self):
+        for section in self.document.traverse(docutils.nodes.section):
+            title = section.children[0].astext()
+            link_id = title.replace(' ', '-')
+            section['ids'] = [link_id]
+
+
+class CreateSectionLabels(docutils.transforms.Transform):
+    """Make labels for each document and each section thereof.
+
+    These labels are referenced in ProcessLocalLinks but can also be
+    used manually with ``:ref:``.
 
     """
 
@@ -1111,11 +1139,7 @@ def apply(self):
             assert section.children
             assert isinstance(section.children[0], docutils.nodes.title)
             title = section.children[0].astext()
-            if file_ext.lower() == '.ipynb':
-                link_id = title.replace(' ', '-')
-                section['ids'] = [link_id]
-            else:
-                link_id = section['ids'][0]
+            link_id = section['ids'][0]
             label = '/' + env.docname + file_ext + '#' + link_id
             label = label.lower()
             env.domaindata['std']['labels'][label] = (
@@ -1132,7 +1156,15 @@ def apply(self):
                     env.docname, '')
                 i_still_have_to_create_the_document_label = False
 
-        # Create labels for domain-specific object signatures
+
+class CreateDomainObjectLabels(docutils.transforms.Transform):
+    """Create labels for domain-specific object signatures."""
+
+    default_priority = 250  # About the same as CreateSectionLabels
+
+    def apply(self):
+        env = self.document.settings.env
+        file_ext = os.path.splitext(env.doc2path(env.docname))[1]
         for sig in self.document.traverse(sphinx.addnodes.desc_signature):
             try:
                 title = sig['ids'][0]
@@ -1420,6 +1452,8 @@ def setup(app):
     app.connect('html-collect-pages', html_collect_pages)
     app.connect('env-purge-doc', env_purge_doc)
     app.add_transform(CreateSectionLabels)
+    app.add_transform(CreateDomainObjectLabels)
+    app.add_transform(ProcessLocalLinks)
 
     # Make docutils' "code" directive (generated by markdown2rst/pandoc)
     # behave like Sphinx's "code-block",