Generated device driver docs

doc/CMakeLists.txt

@@ -148,6 +148,7 @@ file(GLOB_RECURSE  DOXY_SOURCES
   ${ZEPHYR_BASE}/lib/libc/*.[c,h,S]
   ${ZEPHYR_BASE}/subsys/testsuite/ztest/include/*.[h,c,S]
   ${ZEPHYR_BASE}/tests/*.[h,c,S]
+  ${ZEPHYR_BASE}/drivers/*.[c,h,S]
   )
 # For debug. Also find generated list in doc/_build/(build.ninja|CMakeFiles/)
 # message("DOXY_SOURCES= " ${DOXY_SOURCES})

doc/conf.py

@@ -51,6 +51,7 @@
     'zephyr.application',
     'zephyr.html_redirects',
     'only.eager_only',
+    'zephyr.dtcompatible-role',
     'zephyr.link-roles',
     'sphinx_tabs.tabs'
 ]

doc/extensions/zephyr/dtcompatible-role.py

@@ -0,0 +1,44 @@
+# Copyright (c) 2020 Nordic Semiconductor ASA
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""
+A Sphinx extension for documenting devicetree content. It adds a role and a
+directive with the same name, 'dtcompatible'.
+
+:dtcompatible:`vnd,foo`
+
+  This role can be used inline to make a reference to the generated
+  documentation for a devicetree
+  compatible given as argument.
+
+  For example, :dtcompatible:`vnd,foo` would create a reference to the
+  generated documentation page for the devicetree binding handling
+  compatible "vnd,foo".
+
+  There may be more than page for a single compatible. For example,
+  that happens if a binding behaves differently depending on the bus the
+  node is on. If that occurs, the reference points at a "disambiguation"
+  page which links out to all the possibilities, similarly to how Wikipedia
+  disambiguation pages work.
+
+  The Zephyr documentation uses the standard :option: role to refer
+  to Kconfig options. The :dtcompatible: option is like that, except
+  using its own role to avoid using one that already has a standard meaning.
+  (The :option: role is meant for documenting options to command-line programs,
+  not Kconfig symbols.)
+
+.. dtcompatible:: vnd,foo
+
+  This directive marks the page where the :dtcompatible: role link goes.
+  Users should not use it directly. The generated bindings documentation will
+  define these in the right places.
+"""
+
+def setup(app):
+    app.add_crossref_type('dtcompatible', 'dtcompatible')
+
+    return {
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }

doc/extensions/zephyr/link-roles.py

@@ -4,6 +4,25 @@
 
 # based on http://protips.readthedocs.io/link-roles.html
 
+"""
+This file contains Sphinx extensions for the following Zephyr-specific
+documentation roles:
+
+:zephyr_file:
+  Create a link to a file within the zephyr repository tree.
+  The link is to an HTML view of the file as a blob on a Git forge.
+
+  The version displayed corresponds to the current tag if
+  HEAD points at a tag, or the 'master' branch otherwise.
+
+  For example, :zephyr_file:`doc/extensions/zephyr/link-roles.py`
+  creates a link to this file on GitHub by default.
+
+:zephyr_raw:
+  Like ``:zephyr_file:``, but for "raw" output, rather than
+  the usual fancy UI for viewing a git blob's contents.
+"""
+
 from __future__ import print_function
 from __future__ import unicode_literals
 import re

doc/guides/dts/bindings.rst

@@ -15,6 +15,11 @@ dt-schema tools used by the Linux kernel). With one exception in
 :ref:`dt-inferred-bindings` the build system uses bindings when generating
 code for :ref:`dt-from-c`.
 
+.. note::
+
+   See the :ref:`devicetree_binding_index` for information on existing
+   bindings.
+
 .. _dt-binding-compat:
 
 Mapping nodes to bindings