Implemented docutils custom role that renders a link to current documentation page...

Provided documentation of the role.

diff --git a/docs/en/contribute/documenting-code.rst b/docs/en/contribute/documenting-code.rst
index 37f71deeb45781fe210e7d9ebd7325c4097bfc33..80cbe1cf77702407e327d1e0424a2d2ac852c485 100644 (file)
--- a/docs/en/contribute/documenting-code.rst
+++ b/docs/en/contribute/documenting-code.rst
@@ -165,6 +165,20 @@ How it renders:
 
 A check is added to the CI build script, which searches RST files for presence of hard-coded links (identified by tree/master, blob/master, or raw/master part of the URL). This check can be run manually: ``cd docs`` and then ``make gh-linkcheck``.
 
+
+Linking Language Versions
+-------------------------
+
+Switching between documentation in different languages may be done using ``:link_to_translation:`` custom role. The role placed on a page of documentation provides a link to the same page in a language specified as a parameter. Examples below show how to enter links to Chinese and English versions of documentation::
+
+    :link_to_translation:`zh_CN:中文版`
+    :link_to_translation:`en:English`
+
+The language is specified using standard abbreviations like ``en`` or ``zh_CN``. The text after last semicolon is not standardized and may be entered depending on the context where the link is placed, e.g.::
+
+    :link_to_translation:`en:see description in English`
+
+
 .. _add-illustrations:
 
 Add Illustrations

diff --git a/docs/link-roles.py b/docs/link-roles.py
index 7bfe353921812b218bfccee5a88cfe8028fa0051..9760f495027a0031830798aa4447a76dbfae4363 100644 (file)
--- a/docs/link-roles.py
+++ b/docs/link-roles.py
@@ -1,6 +1,7 @@
 # based on http://protips.readthedocs.io/link-roles.html
 
 import re
+import os
 from docutils import nodes
 from local_util import run_cmd_get_output
 
@@ -13,10 +14,11 @@ def get_github_rev():
         path = tag
     return path
 
-
 def setup(app):
-    baseurl = 'https://github.com/espressif/esp-idf'
     rev = get_github_rev()
+
+    # links to files or folders on the GitHub
+    baseurl = 'https://github.com/espressif/esp-idf'
     app.add_role('idf', autolink('{}/tree/{}/%s'.format(baseurl, rev)))
     app.add_role('idf_file', autolink('{}/blob/{}/%s'.format(baseurl, rev)))
     app.add_role('idf_raw', autolink('{}/raw/{}/%s'.format(baseurl, rev)))
@@ -27,6 +29,19 @@ def setup(app):
     app.add_role('example_file', autolink('{}/blob/{}/examples/%s'.format(baseurl, rev)))
     app.add_role('example_raw', autolink('{}/raw/{}/examples/%s'.format(baseurl, rev)))
 
+    # link to the current documentation file in specific language version
+    on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
+    if on_rtd:
+        # provide RTD specific commit identification to be included in the link
+        tag_rev = 'latest'
+        if (run_cmd_get_output('git rev-parse --short HEAD') != rev):
+            tag_rev = rev
+    else:
+        # if not on the RTD then provide generic identification 
+        tag_rev = run_cmd_get_output('git describe --always')
+
+    app.add_role('link_to_translation', crosslink('%s../../%s/{}/%s.html'.format(tag_rev)))
+
 def autolink(pattern):
     def role(name, rawtext, text, lineno, inliner, options={}, content=[]):
         m = re.search('(.*)\s*<(.*)>', text)
@@ -40,3 +55,14 @@ def autolink(pattern):
         node = nodes.reference(rawtext, link_text, refuri=url, **options)
         return [node], []
     return role
+
+def crosslink(pattern):
+    def role(name, rawtext, text, lineno, inliner, options={}, content=[]):
+        (language, link_text) = text.split(':')
+        docname = inliner.document.settings.env.docname
+        doc_path = inliner.document.settings.env.doc2path(docname, None, None)
+        return_path = '../' * doc_path.count('/') 
+        url = pattern % (return_path, language, docname)
+        node = nodes.reference(rawtext, link_text, refuri=url, **options)
+        return [node], []
+    return role