Re: DevDocs support for zephyr docs?

Marti Bolivar

On Thu, Mar 15, 2018 at 1:04 PM, Kinder, David B <> wrote:
No I haven't heard of DevDocs.

What does the Zephyr community think about such a tool (or others such as dash) that present project API documentation to developers?

What would make the Zephyr Project API material more useful?

For example, should we publish the doxygen-generated html public API documentation instead of (or in addition to) the Sphinx-generated rendering found at

I think that the Sphinx content that's rendered by Breathe is a great start (and I've used Breathe to document other projects before, and believe it has good features). However, in my opinion, there are problems with the current output that make it unlikely to be used much in practice by Zephyr developers.

Here are my favorites:

- The header files where the APIs are declared is not clear. What, for example, do I include to use these APIs?

- The output for defines is not useful in the case of macros which are just numbers:

What is K_POLL_TYPE_IGNORE? How do I use it -- are there any examples? Do I just need to read the code to see what its value is? ... but what header is it declared in?

- The lack of consistent cross-referencing is a problem. Let's say I want to use k_thread_access_grant():

What is a struct k_thread; where are its API docs? Note that this is not always a problem, e.g. I do get a reference to k_id_t from here:

In short, the Breathe "doxygengroup" output is not enough on its own to use an API without falling back on the source code. Besides some output (as the K_POLL_TYPE_IGNORE example) just not being useful, other missing critical context includes explanatory text alongside the API docs that describes (or links to more information on) common use cases, motivation, examples, etc.

- a reference book on an API (e.g.
- other API doc systems, like Java's (e.g. see java.util in
Or do developers prefer to just "read the code" (header files in particular)?

In my opinion, given the problems above, reading the code (either directly, or using the help of an indexer like cscope, as I prefer) is the only practical choice for developers given the above problems. There's simply not enough information in the doxygengroup output to be useful, at least as it's currently implemented in Breathe and used in Zephyr. That's not ideal IMO -- while some developers always will prefer reading the code, "real" API docs are needed.

Here are some possible alternatives:

- Zephyr could continue to use Doxygen, reST, and Breathe only, but use lower-level Breathe directives like doxygenfunction and doxygendefine to pull in API documentation in appropriate places in a hand-written API description file (probably working with upstream Breathe as necessary to add any missing information and fix issues).

- Add in a publicly available searchable code index like LXR (, with an example live instance at or OpenGrok (, example live instance at, and perhaps link to it from the restructuredText (perhaps with a custom directive).

- Combinations of these, etc.


-- david

> -----Original Message-----
> From: Kumar Gala [mailto:kumar.gala@...]
> Sent: Thursday, March 15, 2018 9:42 AM
> To: Kinder, David B <>
> Cc:
> Subject: DevDocs support for zephyr docs?
> David,
> I was wondering if you’ve ever come across the DevDocs project
>  I wonder what it might take to get
> Zephyr docs supported.
> - k
Zephyr-devel mailing list

Join to automatically receive all group messages.