NF: Intersphinx mapping to link to handbook content (fixes gh-4034)

datalad/core/distributed/clone.py

@@ -99,7 +99,7 @@ class Clone(Interface):
 
     .. seealso::
 
-      http://handbook.datalad.org/en/latest/usecases/datastorage_for_institutions.html
+      :ref:`handbook:3-001`
         More information on Remote Indexed Archive (RIA) stores
     """
     # by default ignore everything but install results

datalad/interface/base.py

@@ -15,6 +15,7 @@
 import logging
 lgr = logging.getLogger('datalad.interface.base')
 
+import os
 import sys
 import re
 import textwrap
@@ -239,6 +240,19 @@ def alter_interface_docs_for_api(docs):
         lambda match: match.group(1),
         docs,
         flags=re.MULTILINE | re.DOTALL)
+    if 'DATALAD_SPHINX_RUN' not in os.environ:
+        # remove :role:`...` RST markup for cmdline docs
+        docs = re.sub(
+            r':\S+:`[^`]*`[\\]*',
+            lambda match: ':'.join(match.group(0).split(':')[2:]).strip('`\\'),
+            docs,
+            flags=re.MULTILINE | re.DOTALL)
+        # make the handbook doc references more accessible
+        # the URL is a redirect configured at readthedocs
+        docs = re.sub(
+            r'(handbook:[0-9]-[0-9]*)',
+            '\\1 (http://handbook.datalad.org/symbols)',
+            docs)
     docs = re.sub(
         r'\|\| REFLOW \>\>\n(.*?)\<\< REFLOW \|\|',
         lambda match: textwrap.fill(match.group(1)),
@@ -282,6 +296,12 @@ def alter_interface_docs_for_cmdline(docs):
         lambda match: ':'.join(match.group(0).split(':')[2:]).strip('`\\'),
         docs,
         flags=re.MULTILINE | re.DOTALL)
+    # make the handbook doc references more accessible
+    # the URL is a redirect configured at readthedocs
+    docs = re.sub(
+        r'(handbook:[0-9]-[0-9]*)',
+        '\\1 (http://handbook.datalad.org/symbols)',
+        docs)
     # remove None constraint. In general, `None` on the cmdline means don't
     # give option at all, but specifying `None` explicitly is practically
     # impossible

docs/Makefile

@@ -3,15 +3,10 @@
 
 # You can set these variables from the command line.
 SPHINXOPTS    = -W
-SPHINXBUILD   = sphinx-build
+SPHINXBUILD   = DATALAD_SPHINX_RUN=1 sphinx-build
 PAPER         =
 BUILDDIR      = build
 
-# User-friendly check for sphinx-build
-ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
-$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
-endif
-
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter

docs/source/conf.py

@@ -336,4 +336,12 @@ def setup(sphinx):
 
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'https://docs.python.org/': None}
+intersphinx_mapping = {
+    'handbook': (
+        # use handbook matching "major" release
+        'http://handbook.datalad.org/en/{version}/'.format(
+            #version='.'.join(datalad.__version__.split('.', maxsplit=2)[:2]),
+            version='latest',
+        ),
+        None),
+}