[wip] doc: add driver index

We have thorough existing documentation on the abstract driver model.

We have some documentation on individual APIs (though the generated
content is not very useful and should probably be looked at; I suspect
99.9% of users are just reading the doxygen comments in the source
code instead of looking at these pages).

We do not, however, have documentation for actual device drivers, or
information about what devicetree compatibles and Kconfig options they
are associated with.

This patch is a proof of concept showing how the previous patches in
the series can be stitched together into an index of existing drivers
that cross-references DT and Kconfig as needed, with content
coming from the sources.

Signed-off-by: Martí Bolívar <[email protected]>

Author: mbolivar-nordic

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
@@ -300,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
 #
@@ -414,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
@@ -427,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/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/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