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
2 changed files with 42 additions and 2 deletions
|
@ -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``.
|
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:
|
||||||
|
|
||||||
Add Illustrations
|
Add Illustrations
|
||||||
|
|
|
@ -1,6 +1,7 @@
|
||||||
# based on http://protips.readthedocs.io/link-roles.html
|
# based on http://protips.readthedocs.io/link-roles.html
|
||||||
|
|
||||||
import re
|
import re
|
||||||
|
import os
|
||||||
from docutils import nodes
|
from docutils import nodes
|
||||||
from local_util import run_cmd_get_output
|
from local_util import run_cmd_get_output
|
||||||
|
|
||||||
|
@ -13,10 +14,11 @@ def get_github_rev():
|
||||||
path = tag
|
path = tag
|
||||||
return path
|
return path
|
||||||
|
|
||||||
|
|
||||||
def setup(app):
|
def setup(app):
|
||||||
baseurl = 'https://github.com/espressif/esp-idf'
|
|
||||||
rev = get_github_rev()
|
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', autolink('{}/tree/{}/%s'.format(baseurl, rev)))
|
||||||
app.add_role('idf_file', autolink('{}/blob/{}/%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)))
|
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_file', autolink('{}/blob/{}/examples/%s'.format(baseurl, rev)))
|
||||||
app.add_role('example_raw', autolink('{}/raw/{}/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 autolink(pattern):
|
||||||
def role(name, rawtext, text, lineno, inliner, options={}, content=[]):
|
def role(name, rawtext, text, lineno, inliner, options={}, content=[]):
|
||||||
m = re.search('(.*)\s*<(.*)>', text)
|
m = re.search('(.*)\s*<(.*)>', text)
|
||||||
|
@ -40,3 +55,14 @@ def autolink(pattern):
|
||||||
node = nodes.reference(rawtext, link_text, refuri=url, **options)
|
node = nodes.reference(rawtext, link_text, refuri=url, **options)
|
||||||
return [node], []
|
return [node], []
|
||||||
return role
|
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