Docs: add more sphinx :labels:

docs/README.rst

@@ -22,6 +22,27 @@ On a debian system, you can install the needed dependencies with:
       python3-sphinx \
       python3-sphinx-rtd-theme
 
+Sphinx extensions
+-----------------
+
+Some ad-hoc reference kinds are supported.
+
+- ``:package-src:`name``` or ``:package-src:`text<name>``` points
+  to the gitlab source tree viewer where the `.opam` for the package
+  is located
+- ``:package:`name``` or ``:package:`text<name>``` now points
+  either to the `odoc` page, or if it doesn't exist, to the gitlab
+  source tree viewer
+- ``:package-name:`name``` or ``:package-name:`text<name>``` just
+  displays the package name (no link), checking that the package
+  exists
+- ``:src:`/path/to/file/or/dir``` or
+  ``:src:`text</path/to/file/or/dir>``` points to the gitlab source
+  tree viewer
+- ``:opam:`package``` or ``:opam:`text<package>``` points to the
+  package page on ``opam.ocaml.org``, version number is supported
+  (``package.version``)
+
 OCaml documentation
 -------------------
 

docs/_extensions/tezos_custom_roles.py

@@ -1,16 +1,79 @@
 from docutils import nodes
 import os
 import os.path
+import re
 
 def setup(app):
     app.add_role('package', package_role)
+    app.add_role('package-name', package_role)
+    app.add_role('package-src', package_role)
+    app.add_role('opam', opam_role)
+    app.add_role('src', src_role)
+
+def find_dot_opam(name):
+    for path, dirs, files in os.walk('..'):
+        for file in files:
+            if file == name + '.opam':
+                return path.lstrip('../')
+    raise ValueError('opam file ' + name + '.opam does not exist in the odoc')
 
 def package_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
     rel_lvl = inliner.document.current_source.replace(os.getcwd(),'').count('/')
-    if not os.path.exists('_build/api/odoc/'+text):
-        raise ValueError('opam package ' + text + ' does not exist in the odoc')
-    url = "api/api-inline.html#" + text + '/index.html'
-    for i in range(1,rel_lvl):
+    parts = re.match("^([^<>]*)<([^<>]*)>$", text)
+    if parts:
+      text = parts.group(2)
+      lib = parts.group(1)
+    else:
+      lib = text
+    src = find_dot_opam(lib)
+    branch = os.environ.get('CI_COMMIT_REF_NAME')
+    if not branch:
+        branch = 'master'
+    src_url = "https://gitlab.com/tezos/tezos/tree/" + branch + "/" + src
+    if os.path.isdir('_build/api/odoc/'+lib):
+      if os.path.isdir(os.path.join('_build','api','odoc',lib,lib.replace('-','_').capitalize())):
+        lib = lib + '/' + lib.replace('-','_').capitalize()
+      url = "api/api-inline.html#" + lib + '/index.html'
+      for i in range(1,rel_lvl):
         url = '../' + url
+    else:
+      url = src_url
+    if name == 'package':
+      node = nodes.reference(rawtext, text, refuri=url, **options)
+    elif name == 'package-name':
+      node = nodes.literal(text, text)
+    elif name == 'package-src':
+      node = nodes.reference(rawtext, src, refuri=src_url, **options)
+    return [node], []
+
+def opam_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
+    rel_lvl = inliner.document.current_source.replace(os.getcwd(),'').count('/')
+    parts = re.match("^([^<>]*)<([^<>]*)>$", text)
+    if parts:
+      text = parts.group(2)
+      lib = parts.group(1)
+    else:
+      lib = text
+    tagged = re.match('([^.]+)[.].*', lib)
+    if tagged:
+      url = "https://opam.ocaml.org/packages/" + tagged.group(1) + "/" + lib
+    else:
+      url = "https://opam.ocaml.org/packages/" + lib
+    node = nodes.reference(rawtext, text, refuri=url, **options)
+    return [node], []
+
+def src_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
+    rel_lvl = inliner.document.current_source.replace(os.getcwd(),'').count('/')
+    parts = re.match("^([^<>]*)<([^<>]*)>$", text)
+    if parts:
+      text = parts.group(2)
+      src = parts.group(1)
+    else:
+      src = text
+      text = text
+    branch = os.environ.get('CI_COMMIT_REF_NAME')
+    if not branch:
+        branch = 'master'
+    url = "https://gitlab.com/tezos/tezos/tree/" + branch + "/" + src
     node = nodes.reference(rawtext, text, refuri=url, **options)
     return [node], []