conf.py: add linux:man and core:man refs support

Add domainrefs.py from flux-core and suitable addition to conf.py to
get easy manpage links to various linux and flux-core manpages.

conf.py

@@ -21,8 +21,8 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
 import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+import sys
+sys.path.insert(0, os.path.abspath('.'))
 
 
 # -- Project information -----------------------------------------------------
@@ -52,6 +52,7 @@
     "sphinx.ext.intersphinx",
     'sphinxcontrib.spelling',
     'sphinx_copybutton',
+    'domainrefs'
 ]
 
 # sphinxcontrib.spelling settings
@@ -70,6 +71,37 @@
 master_doc = 'index'
 source_suffix = '.rst'
 
+domainrefs = {
+    'linux:man1': {
+        'text': '%s(1)',
+        'url': 'http://man7.org/linux/man-pages/man1/%s.1.html',
+    },
+    'linux:man2': {
+        'text': '%s(2)',
+        'url': 'http://man7.org/linux/man-pages/man2/%s.2.html',
+    },
+    'linux:man3': {
+        'text': '%s(3)',
+        'url': 'http://man7.org/linux/man-pages/man3/%s.3.html',
+    },
+    'linux:man7': {
+        'text': '%s(7)',
+        'url': 'http://man7.org/linux/man-pages/man7/%s.7.html',
+    },
+    'core:man1': {
+        'text': '%s(1)',
+        'url': 'https://flux-framework.readthedocs.io/projects/flux-core/en/latest/man1/%s.html',
+    },
+    'core:man3': {
+        'text': '%s(3)',
+        'url': 'https://flux-framework.readthedocs.io/projects/flux-core/en/latest/man3/%s.html',
+    },
+    'core:man7': {
+        'text': '%s(7)',
+        'url': 'https://flux-framework.readthedocs.io/projects/flux-core/en/latest/man7/%s.html',
+    },
+}
+
 # -- Options for Intersphinx -------------------------------------------------
 
 intersphinx_mapping = {

domainrefs.py

@@ -0,0 +1,72 @@
+"""
+Originally from:
+
+  https://github.com/mitogen-hq/mitogen/blob/master/docs/domainrefs.py
+
+Copyright 2021, the Mitogen authors
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+this list of conditions and the following disclaimer in the documentation
+and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+may be used to endorse or promote products derived from this software without
+specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+"""
+import functools
+import re
+
+import docutils.nodes
+import docutils.utils
+
+
+CUSTOM_RE = re.compile('(.*) <(.*)>')
+
+
+def role(config, role, rawtext, text, lineno, inliner, options={}, content=[]):
+    template = 'https://docs.ansible.com/ansible/latest/modules/%s_module.html'
+
+    match = CUSTOM_RE.match(text)
+    if match:  # "custom text <real link>"
+        title = match.group(1)
+        text = match.group(2)
+    elif text.startswith('~'):  # brief
+        text = text[1:]
+        title = config.get('brief', '%s') % (
+            docutils.utils.unescape(text),
+        )
+    else:
+        title = config.get('text', '%s') % (
+            docutils.utils.unescape(text),
+        )
+
+    node = docutils.nodes.reference(
+        rawsource=rawtext,
+        text=title,
+        refuri=config['url'] % (text,),
+        **options
+    )
+
+    return [node], []
+
+
+def setup(app):
+    for name, info in app.config._raw_config['domainrefs'].items():
+        app.add_role(name, functools.partial(role, info))

requirements.txt

@@ -3,3 +3,4 @@ Sphinx
 sphinxcontrib-spelling
 sphinx-rtd-theme>=0.5.2
 sphinx-copybutton
+docutils>=0.14,<0.18