Implemented docutils custom role that renders a link to current documentation page on Read The Docs in another language version
Provided documentation of the role.
This commit is contained in:
parent
03414b1f39
commit
d754b53ae2
|
@ -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
|
||||
|
|
|
@ -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
|
||||
|
|
Loading…
Reference in a new issue