Merge branch 'doc/view_github_link' into 'master'

docs: add 'edit-on-github' link to html theme

Closes IDF-1504

See merge request espressif/esp-idf!8629

docs/conf_common.py

@@ -23,6 +23,8 @@ import re
 import subprocess
 from sanitize_version import sanitize_version
 from idf_extensions.util import download_file_if_missing
+from get_github_rev import get_github_rev
+
 
 # build_docs on the CI server sometimes fails under Python3. This is a workaround:
 sys.setrecursionlimit(3500)
@@ -223,6 +225,14 @@ html_redirect_pages = [tuple(line.split(' ')) for line in lines]
 
 html_theme = 'sphinx_idf_theme'
 
+# context used by sphinx_idf_theme
+html_context = {
+    "display_github": True,  # Add 'Edit on Github' link instead of 'View page source'
+    "github_user": "espressif",
+    "github_repo": "esp-idf",
+    "github_version": get_github_rev(),
+}
+
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
@@ -242,6 +252,7 @@ html_theme = 'sphinx_idf_theme'
 # of the sidebar.
 html_logo = "../_static/espressif-logo.svg"
 
+
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
 # pixels large.
@@ -395,6 +406,7 @@ def setup(app):
 
     # Config values pushed by -D using the cmdline is not available when setup is called
     app.connect('config-inited',  setup_config_values)
+    app.connect('config-inited',  setup_html_context)
 
 
 def setup_config_values(app, config):
@@ -410,6 +422,11 @@ def setup_config_values(app, config):
     app.add_config_value('pdf_file', pdf_name, 'env')
 
 
+def setup_html_context(app, config):
+    # Setup path for 'edit on github'-link
+    config.html_context['conf_py_path'] = "/docs/{}/".format(app.config.language)
+
+
 def setup_diag_font(app):
     # blockdiag and other tools require a font which supports their character set
     # the font file is stored on the download server to save repo size

docs/get_github_rev.py

@@ -0,0 +1,15 @@
+import subprocess
+
+
+# Get revision used for constructing github URLs
+def get_github_rev():
+    path = subprocess.check_output(['git', 'rev-parse', '--short', 'HEAD']).strip().decode('utf-8')
+    try:
+        tag = subprocess.check_output(['git', 'describe', '--exact-match']).strip().decode('utf-8')
+    except subprocess.CalledProcessError:
+        tag = None
+    print('Git commit ID: ', path)
+    if tag:
+        print('Git tag: ', tag)
+        return tag
+    return path

docs/idf_extensions/link_roles.py

@@ -8,19 +8,7 @@ import subprocess
 from docutils import nodes
 from collections import namedtuple
 from sphinx.transforms.post_transforms import SphinxPostTransform
-
-
-def get_github_rev():
-    path = subprocess.check_output(['git', 'rev-parse', '--short', 'HEAD']).strip().decode('utf-8')
-    try:
-        tag = subprocess.check_output(['git', 'describe', '--exact-match']).strip().decode('utf-8')
-    except subprocess.CalledProcessError:
-        tag = None
-    print('Git commit ID: ', path)
-    if tag:
-        print('Git tag: ', tag)
-        return tag
-    return path
+from get_github_rev import get_github_rev
 
 
 # Creates a dict of all submodules with the format {submodule_path : (url relative to git root), commit)}