feat(docs): add Chinese translation (jump link) (#5839)

Co-authored-by: YobeZhou <smilezyb@163.com>

docs/_ext/link_roles.py

@@ -0,0 +1,58 @@
+# based on http://protips.readthedocs.io/link-roles.html
+
+#from __future__ import print_function, unicode_literals
+
+import os
+import re
+import subprocess
+from collections import namedtuple
+
+from docutils import nodes
+from sphinx.transforms.post_transforms import SphinxPostTransform
+
+URL_BASE = {
+    "zh_CN": "https://lvgl.100ask.net/"
+}
+
+class translation_link(nodes.Element):
+    """Node for "link_to_translation" role."""
+
+
+# Linking to translation is done at the "writing" stage to avoid issues with the info being cached between builders
+def link_to_translation(name, rawtext, text, lineno, inliner, options={}, content=[]):
+    node = translation_link()
+    node['expr'] = (rawtext, text, options)
+    return [node], []
+
+
+class TranslationLinkNodeTransform(SphinxPostTransform):
+    # Transform needs to happen early to ensure the new reference node is also transformed
+    default_priority = 0
+
+    def run(self, **kwargs):
+        # Only output relative links if building HTML
+        for node in self.document.traverse(translation_link):
+            if 'html' in self.app.builder.name:
+                rawtext, text, options = node['expr']
+                (language, link_text) = text.split(':')
+                env = self.document.settings.env
+                docname = env.docname
+                #doc_path = env.doc2path(docname, False)
+                urlpath = os.environ['LVGL_URLPATH']+'/'
+                return_path = URL_BASE.get(language, "") + urlpath
+                
+                url = '{}.html'.format(os.path.join(return_path, docname))
+
+                node.replace_self(nodes.reference(rawtext, link_text, refuri=url, **options))
+            else:
+                node.replace_self([])
+
+
+def setup(app):
+
+    # link to the current documentation file in specific language version
+    app.add_role('link_to_translation', link_to_translation)
+    app.add_node(translation_link)
+    app.add_post_transform(TranslationLinkNodeTransform)
+
+    return {'parallel_read_safe': True, 'parallel_write_safe': True, 'version': '0.5'}

docs/add_translation.py

@@ -0,0 +1,23 @@
+#!/usr/bin/env python3
+import os
+
+
+def find_files(dir_path, suffix):
+    files = []
+
+    for root, _, filenames in os.walk(dir_path):
+        for filename in filenames:
+            if filename.endswith(suffix):
+                files.append(os.path.join(root, filename))
+    return files
+
+
+
+def exec(temp_directory):
+    files = find_files(temp_directory, '.rst')
+
+    for rst_file in files:
+        with open(rst_file, 'r+', encoding='utf-8') as f:
+            content = f.read()
+            f.seek(0, 0)
+            f.write(':link_to_translation:`zh_CN:[中文]`\n\n' + content)

docs/build.py

@@ -15,6 +15,7 @@ import doc_builder
 import shutil
 import tempfile
 import config_builder
+import add_translation
 
 # due to the modifications that take place to the documentation files
 # when the documentaation builds it is better to copy the source files to a
@@ -76,7 +77,7 @@ def cmd(s):
 
 
 # Get the current branch name
-status, br = subprocess.getstatusoutput("git branch")
+status, br = subprocess.getstatusoutput("git branch --show-current")
 _, gitcommit = subprocess.getstatusoutput("git rev-parse HEAD")
 br = re.sub('\* ', '', br)
 
@@ -135,6 +136,9 @@ with open(os.path.join(temp_directory, 'Doxyfile'), 'wb') as f:
 print("Generate the list of examples")
 ex.exec(temp_directory)
 
+print("Add translation")
+add_translation.exec(temp_directory)
+
 print("Running doxygen")
 cmd('cd "{0}" && doxygen Doxyfile'.format(temp_directory))
 

docs/conf.py

@@ -41,7 +41,8 @@ extensions = [
     'breathe',
     'sphinx_sitemap',
     'lv_example',
-    'sphinx_rtd_dark_mode'
+    'sphinx_rtd_dark_mode',
+    'link_roles'
 ]
 
 default_dark_mode = False

docs/example_list.py

@@ -70,7 +70,7 @@ widgets = {
     "table": "Table",
     "tabview": "Tabview",
     "textarea": "Textarea",
-    "tileview": "Tabview",
+    "tileview": "Tileview",
     "win": "Window",
 }