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

@@ -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: |

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">

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 ---------------------------------------------

doc/index.rst

@@ -117,7 +117,6 @@ Sections
 Indices and Tables
 ******************
 
-* :ref:`configuration_options`
 * :ref:`glossary`
 * :ref:`genindex`