DevDocs support for zephyr docs?


Marti Bolivar
 



On Wed, Mar 21, 2018 at 12:47 PM, Marti Bolivar <marti@...> wrote:



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.


I forgot to write this here, sorry: ", the way you would expect if you were used to:"
 
- a reference book on an API (e.g. https://nostarch.com/download/TLPI_Ch4.pdf)
- other API doc systems, like Java's (e.g. see java.util in https://docs.oracle.com/javase/8/docs/api/)
 



Marti Bolivar
 



On Thu, Mar 15, 2018 at 1:04 PM, Kinder, David B <david.b.kinder@...> 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 http://docs.zephyrproject.org/api/api.html?


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. https://nostarch.com/download/TLPI_Ch4.pdf)
- other API doc systems, like Java's (e.g. see java.util in https://docs.oracle.com/javase/8/docs/api/)
 
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 (https://en.wikipedia.org/wiki/LXR_Cross_Referencer, with an example live instance at https://elixir.bootlin.com) or OpenGrok (http://oracle.github.io/opengrok/, example live instance at http://androidxref.com/), and perhaps link to it from the restructuredText (perhaps with a custom directive).

- Combinations of these, etc.

Thanks,
Marti
 

-- david

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


Kumar Gala
 

I came across this looking for a tool for offline doc usage. Looks interesting and will see how it works for cmake docs. Thought it might be useful for other developers in offline usage cases.

- k

On Mar 15, 2018, at 12:04 PM, Kinder, David B <david.b.kinder@intel.com> 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 http://docs.zephyrproject.org/api/api.html?

Or do developers prefer to just "read the code" (header files in particular)?

-- david

-----Original Message-----
From: Kumar Gala [mailto:kumar.gala@linaro.org]
Sent: Thursday, March 15, 2018 9:42 AM
To: Kinder, David B <david.b.kinder@intel.com>
Cc: zephyr-devel@lists.zephyrproject.org
Subject: DevDocs support for zephyr docs?

David,

I was wondering if you’ve ever come across the DevDocs project
https://github.com/Thibaut/devdocs. I wonder what it might take to get
Zephyr docs supported.

- k


Kinder, David B <david.b.kinder@...>
 

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 http://docs.zephyrproject.org/api/api.html?

Or do developers prefer to just "read the code" (header files in particular)?

-- david

-----Original Message-----
From: Kumar Gala [mailto:kumar.gala@linaro.org]
Sent: Thursday, March 15, 2018 9:42 AM
To: Kinder, David B <david.b.kinder@intel.com>
Cc: zephyr-devel@lists.zephyrproject.org
Subject: DevDocs support for zephyr docs?

David,

I was wondering if you’ve ever come across the DevDocs project
https://github.com/Thibaut/devdocs. I wonder what it might take to get
Zephyr docs supported.

- k


Kumar Gala
 

David,

I was wondering if you’ve ever come across the DevDocs project https://github.com/Thibaut/devdocs. I wonder what it might take to get Zephyr docs supported.

- k