Generated device driver docs

doc/CMakeLists.txt

@@ -92,13 +92,16 @@ set(I18NSPHINXOPTS  ${SPHINXOPTS})
 set(DOXYFILE_IN ${CMAKE_CURRENT_LIST_DIR}/zephyr.doxyfile.in)
 set(DOXYFILE_OUT ${CMAKE_CURRENT_BINARY_DIR}/zephyr.doxyfile)
 set(DOXY_OUT ${CMAKE_CURRENT_BINARY_DIR}/doxygen)
+set(DOXY_XML_OUT ${DOXY_OUT}/xml)
 set(RST_OUT ${CMAKE_CURRENT_BINARY_DIR}/rst)
 set(DOC_LOG ${CMAKE_CURRENT_BINARY_DIR}/doc.log)
 set(DOXY_LOG ${CMAKE_CURRENT_BINARY_DIR}/doxy.log)
 set(SPHINX_LOG ${CMAKE_CURRENT_BINARY_DIR}/sphinx.log)
 set(DOC_WARN ${CMAKE_CURRENT_BINARY_DIR}/doc.warnings)
 set(CONTENT_OUTPUTS ${CMAKE_CURRENT_BINARY_DIR}/extracted-content.txt)
 
+# TODO: need to pass all the modules which have drivers/
+# subdirectories in here too
 configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY)
 
 # This command is used to copy all documentation source files from the
@@ -148,6 +151,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})
@@ -299,6 +303,48 @@ add_custom_target(
 
 set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS ${GEN_DEVICETREE_REST_SCRIPT})
 
+#
+# Generated device driver .rst documents.
+#
+# The device drivers discovered in ${DRIVER_MODULES} are parsed and
+# documentation for them is generated in the directory ${DRIVERS_RST_OUT}.
+# Defaults:
+#
+# - DRIVER_MODULES: ZEPHYR_BASE
+# - DRIVERS_RST_OUT: ${RST_OUT}/doc/drivers
+
+set(GEN_DRIVER_REST_SCRIPT ${CMAKE_CURRENT_LIST_DIR}/scripts/gen_driver_rest.py)
+
+if(NOT DRIVER_MODULES)
+  set(DRIVER_MODULES ${ZEPHYR_BASE})
+endif()
+
+set(DRIVER_MODULES_ARGS)
+foreach(module ${DRIVER_MODULES})
+  list(APPEND DRIVER_MODULES_ARGS --module ${module})
+endforeach()
+
+if(NOT DRIVERS_RST_OUT)
+  set(DRIVERS_RST_OUT ${RST_OUT}/doc/drivers)
+endif()
+
+add_custom_target(
+  drivers
+  COMMAND ${CMAKE_COMMAND} -E env
+  ${PYTHON_EXECUTABLE} ${GEN_DRIVER_REST_SCRIPT}
+    --doxygen-xml ${DOXY_XML_OUT}
+    ${DRIVER_MODULES_ARGS}
+    ${DRIVERS_RST_OUT}
+  VERBATIM
+  WORKING_DIRECTORY ${CMAKE_CURRENT_LIST_DIR}
+  COMMENT "Running gen_drivers_rest.py ${DRIVERS_RST_OUT}"
+  USES_TERMINAL
+)
+
+add_dependencies(drivers doxy_real_modified_times)
+
+set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS ${GEN_DRIVER_REST_SCRIPT})
+
 #
 # HTML section
 #
@@ -413,7 +459,7 @@ endif()
 #
 # Dependencies and final targets
 #
-add_dependencies(html content doxy_real_modified_times kconfig devicetree)
+add_dependencies(html content doxy_real_modified_times kconfig devicetree drivers)
 
 add_custom_target(
   htmldocs
@@ -426,7 +472,7 @@ add_custom_target(
 )
 add_dependencies(doxygen doxy_real_modified_times)
 
-add_dependencies(latex content doxy_real_modified_times kconfig devicetree)
+add_dependencies(latex content doxy_real_modified_times kconfig devicetree drivers)
 
 add_custom_target(
   latexdocs

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/drivers/index.rst

@@ -0,0 +1,44 @@
+.. _device_drivers:
+
+Device Drivers
+##############
+
+This page is an index of device drivers. Each device driver implements a Zephyr
+:ref:`API <api_overview>`. Device drivers are responsible for creating the
+:c:struct:`device` structures at the heart of Zephyr's :ref:`device and driver
+model <device_model_api>`.
+
+To enable a device driver -- i.e. compile and link the driver source code into
+your Zephyr :ref:`application <application>` -- you will typically need to:
+
+- enable the driver using :ref:`Kconfig <kconfig>`
+- configure one or more devices using :ref:`devicetree <dt-guide>`
+
+In order to use the device driver, you will need a pointer to a ``struct
+device`` created by the driver source. This is done with the
+:c:func:`device_get_binding` function, which requires the name of the device.
+For help getting a pointer to a device configured in the devicetree, see
+:ref:`dt-get-device`.
+
+.. Note: there's nothing else in this directory because the toctree is pulling
+   in files created by gen_driver_rest.py.
+
+.. TODO: figure out how to glob this; "*/index.rst" didn't work with plain :glob:
+
+.. toctree::
+
+   adc/index.rst
+   clock_control/index.rst
+   counter/index.rst
+   entropy/index.rst
+   flash/index.rst
+   gpio/index.rst
+   hwinfo/index.rst
+   i2c/index.rst
+   ipm/index.rst
+   pwm/index.rst
+   sensor/index.rst
+   serial/index.rst
+   spi/index.rst
+   usb/index.rst
+   watchdog/index.rst

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

doc/index.rst

@@ -114,6 +114,7 @@ licensing, as described in :ref:`Zephyr_Licensing`.
    development_process/index.rst
    application/index.rst
    reference/index.rst
+   drivers/index.rst
    guides/index.rst
    security/index.rst
    samples/index.rst