doc: add extension for linking github files

When referencing files from the git tree create a link to the file for
easy browsing of header files and other files of interest.

Borrowed from esspresif/esp-idf project and modified for Zephyr.

Signed-off-by: Anas Nashif <anas.nashif@intel.com>

doc/conf.py

@@ -46,7 +46,8 @@ extensions = [
     'sphinx.ext.autodoc',
     'zephyr.application',
     'zephyr.html_redirects',
-    'only.eager_only'
+    'only.eager_only',
+    'zephyr.link-roles'
 ]
 
 # Only use SVG converter when it is really needed, e.g. LaTeX.

doc/extensions/local_util.py

@@ -0,0 +1,65 @@
+# Utility functions used in conf.py
+#
+# Copyright 2017 Espressif Systems (Shanghai) PTE LTD
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http:#www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import unicode_literals
+from io import open
+import os
+import shutil
+import subprocess
+
+
+def run_cmd_get_output(cmd):
+    try:
+        with open(os.devnull, 'w') as devnull:
+            output = subprocess.check_output(cmd, stderr=devnull, shell=True).strip()
+    except subprocess.CalledProcessError as e:
+        output = e.output.decode('ascii')
+
+    return output
+
+
+def files_equal(path_1, path_2):
+    if not os.path.exists(path_1) or not os.path.exists(path_2):
+        return False
+    file_1_contents = ''
+    with open(path_1, "r", encoding='utf-8') as f_1:
+        file_1_contents = f_1.read()
+    file_2_contents = ''
+    with open(path_2, "r", encoding='utf-8') as f_2:
+        file_2_contents = f_2.read()
+    return file_1_contents == file_2_contents
+
+
+def copy_file_if_modified(src_file_path, dst_file_path):
+    if not files_equal(src_file_path, dst_file_path):
+        dst_dir_name = os.path.dirname(dst_file_path)
+        if not os.path.isdir(dst_dir_name):
+            os.makedirs(dst_dir_name)
+        shutil.copy(src_file_path, dst_file_path)
+
+
+def copy_if_modified(src_path, dst_path):
+    if os.path.isfile(src_path):
+        copy_file_if_modified(src_path, dst_path)
+        return
+
+    src_path_len = len(src_path)
+    for root, dirs, files in os.walk(src_path):
+        for src_file_name in files:
+            src_file_path = os.path.join(root, src_file_name)
+            dst_file_path = os.path.join(dst_path + root[src_path_len:], src_file_name)
+            copy_file_if_modified(src_file_path, dst_file_path)
+

doc/extensions/zephyr/link-roles.py

@@ -0,0 +1,44 @@
+# Copyright (c) 2019 Intel Corporation
+#
+# SPDX-License-Identifier: Apache-2.0
+
+# based on http://protips.readthedocs.io/link-roles.html
+
+from __future__ import print_function
+from __future__ import unicode_literals
+import re
+import os
+from docutils import nodes
+from local_util import run_cmd_get_output
+
+
+def get_github_rev():
+    tag = run_cmd_get_output('git describe --exact-match')
+    if len(tag):
+        return(tag)
+    else:
+        return 'master'
+
+
+def setup(app):
+    rev = get_github_rev()
+
+    # links to files or folders on the GitHub
+    baseurl = 'https://github.com/zephyrproject-rtos/zephyr'
+    app.add_role('zephyr_file', autolink('{}/blob/{}/%s'.format(baseurl, rev)))
+    app.add_role('zephyr_raw', autolink('{}/raw/{}/%s'.format(baseurl, rev)))
+
+
+def autolink(pattern):
+    def role(name, rawtext, text, lineno, inliner, options={}, content=[]):
+        m = re.search('(.*)\s*<(.*)>', text)  # noqa: W605 - regular expression
+        if m:
+            link_text = m.group(1)
+            link = m.group(2)
+        else:
+            link_text = text
+            link = text
+        url = pattern % (link,)
+        node = nodes.reference(rawtext, link_text, refuri=url, **options)
+        return [node], []
+    return role