From b4f968cf9d50fa85436c19d4b2fe67bb4e0f90ad Mon Sep 17 00:00:00 2001
From: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Date: Thu, 28 Oct 2021 18:57:20 +0200
Subject: [PATCH] doc: add a toctree with reference material

Add a new toctree with reference material, including:

- API docs (Doxygen)
- Kconfig options
- Devicetree bindings

Note that the toctree is rendered manually due to the limitations Sphinx
has when it comes to including relative URLs. Hardcoding absolute URLs
in toctrees is possible, but that means we'd need to update the toctree
on every release (to point to /version/ URL), and downstream users of
the documentation would have to manually patch the toctree with their
own URL. In order to make local builds work, version prefix is only
added if publish tag is provided.

Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
---
 .github/workflows/doc-build.yml |  2 +-
 doc/_templates/layout.html      | 12 ++++++++++++
 doc/conf.py                     |  8 ++++++++
 doc/index.rst                   |  1 -
 4 files changed, 21 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/doc-build.yml b/.github/workflows/doc-build.yml
index 42812ae5199..e0a73cca4b4 100644
--- a/.github/workflows/doc-build.yml
+++ b/.github/workflows/doc-build.yml
@@ -73,7 +73,7 @@ jobs:
           DOC_TAG="development"
         fi
 
-        DOC_TAG=${DOC_TAG} SPHINXOPTS="-q -W -j auto" make -C doc html
+        DOC_TAG=${DOC_TAG} SPHINXOPTS="-q -W -j auto -t publish" make -C doc html
 
     - name: compress-docs
       run: |
diff --git a/doc/_templates/layout.html b/doc/_templates/layout.html
index 0db13972a1f..205b2488555 100644
--- a/doc/_templates/layout.html
+++ b/doc/_templates/layout.html
@@ -17,6 +17,18 @@
 {% block menu %}
   {% include "zversions.html" %}
   {{ super() }}
+  {% if reference_links %}
+  <div class="toctree-wrapper compound">
+    <p class="caption"><span class="caption-text">Reference</span></p>
+    <ul>
+      {% for title, url in reference_links.items() %}
+      <li class="toctree-l1">
+        <a class="reference internal" href="{{ url }}">{{ title }}</a>
+      </li>
+      {% endfor %}
+    </ul>
+  </div>
+  {% endif %}
 {% endblock %}
 {% block extrahead %}
   <meta name="color-scheme" content="dark light">
diff --git a/doc/conf.py b/doc/conf.py
index 5694d134a38..5b674b2ea78 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -135,6 +135,9 @@ html_show_sphinx = False
 html_search_scorer = str(ZEPHYR_BASE / "doc" / "_static" / "js" / "scorer.js")
 
 is_release = tags.has("release")  # pylint: disable=undefined-variable
+reference_prefix = ""
+if tags.has("publish"):  # pylint: disable=undefined-variable
+    reference_prefix = f"/{version}" if is_release else "/latest"
 docs_title = "Docs / {}".format(version if is_release else "Latest")
 html_context = {
     "show_license": True,
@@ -151,6 +154,11 @@ html_context = {
         ("1.14.1", "/1.14.1/"),
     ),
     "display_vcs_link": True,
+    "reference_links": {
+        "API": f"{reference_prefix}/doxygen/html/index.html",
+        "Kconfig Options": f"{reference_prefix}/reference/kconfig/index.html",
+        "Devicetree Bindings": f"{reference_prefix}/reference/devicetree/bindings.html",
+    }
 }
 
 # -- Options for LaTeX output ---------------------------------------------
diff --git a/doc/index.rst b/doc/index.rst
index 2046f607167..b43a7eab531 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -117,7 +117,6 @@ Sections
 Indices and Tables
 ******************
 
-* :ref:`configuration_options`
 * :ref:`glossary`
 * :ref:`genindex`