[Doc] How to link dts bindings with Kconfig flags

[erwango]

Is your enhancement proposal related to a problem? Please describe. DTS bindings are now available in zephyr documentation (https://docs.zephyrproject.org/latest/reference/devicetree/bindings.html) and maintainers have a way to document these important pieces of driver configuration. The last important missing piece of information is to indicate how a driver should be enabled, operation typically achieved using Kconfig flags.

This piece of info would would be missing to automatize generation of supported features in boards documentation (cf https://github.com/zephyrproject-rtos/zephyr/pull/29652/).

One easy way to get this link would be to document drivers matching Kconfig flag in dts bindings flag directly. But, as said @mbolivar-nordic: "kind of defeats the 'OS independent' goal for bindings IMO".

So I'm raising this issue in order to reach an agreement on how to document dts bindings Kconfig relation w/o breaking OS independent promises.

[erwango]

@mbolivar-nordic, @MaureenHelm, @galak

[mbolivar-nordic]

I did some prototyping on this last night. So far I have a way for drivers to declare (via Doxygen) what devicetree compatibles they support, and build an index mapping compatible(s) <-> driver(s) from that.

Note that this map can be many-to-many. It's not a function. A single compatible can be handled by multiple drivers. A single driver can handle multiple compatibles.

Next steps are to generate documentation pages for these drivers and include the detailed description (again from Doxygen) into the Sphinx pages. I verified that the usual ways of embedding restructured text work. That allows us to say something like this in a driver file comment:

/**
 * @file
 * @dtcompatible{vnd,foo}
 * This the Foo driver for Vnd devices. To enable this driver, set :option:`CONFIG_FOO` ...
 */

And the :option: part provides a link to the existing Kconfig index.

I will post a proof of concept sometime this week.

[mbolivar-nordic]

cc @pabigot

[erwango]

I did some prototyping on this last night. So far I have a way for drivers to declare (via Doxygen) what devicetree compatibles they support, and build an index mapping compatible(s) <-> driver(s) from that.

I'm fine with the approach! Txs @mbolivar-nordic. One tiny reservation is that it will rely purely on developer and reviewers. Maybe and automated check could be added, or we can get the doc generation could fail if not present ?

[mbolivar-nordic]

One tiny reservation is that it will rely purely on developer and reviewers. Maybe and automated check could be added, or we can get the doc generation could fail if not present ?

Sure, I'm happy to discuss and add CI checks like that depending on what subsystem maintainers decide should be required for driver documentation.

[mbolivar-nordic]

Sorry for the delay, but here is a draft: https://github.com/zephyrproject-rtos/zephyr/pull/30104

There is a new "device drivers" index that pulls in Doxygen content from driver sources. It's at top level and is available on the sidebar.

[mbolivar-nordic]

Sorry for the delay, but here is a draft: #30104

any comments on this?

[erwango]

It's in my TODO list, sorry for the delay.

[zephyrbot]

Hi @carlescufi, @kartben,

This issue, marked as an Enhancement, was opened a while ago and did not get any traction. It was just assigned to you based on the labels. If you don't consider yourself the right person to address this issue, please re-assing it to the right person.

Please take a moment to review if the issue is still relevant to the project. If it is, please provide feedback and direction on how to move forward. If it is not, has already been addressed, is a duplicate, or is no longer relevant, please close it with a short comment explaining the reason.

@erwango you are also encouraged to help moving this issue forward by providing additional information and confirming this request/issue is still relevant to you.

Thanks!

[erwango]

@kartben Feel free to close if this looks as a duplicate or if direction is not the good one