Automatically generate API overview documentation

[edersondisouza]

This PR should address #50922. It basically:

• Generate \since tags from doxgen and git (it may not be perfect, but it's a fairly comprehensive start);
• Manually fix add some based on current information from doc/develop/api.overview.rst;
• Add \version (showing stability level) based on information from doc/develop/api.overview.rst;
• Use all new info (\since and \version) to generate the new API overview page, which is basically an improved version of doxygen own "Modules index" page.

More details of each step are on the commit messages. Two things that still stand out:

• To parse the doxygen XML info, I've used its own "doxmlparser" Python lib, but it needs to be installed from the sources, as there's no package on PyPi. There's an open issue at doxygen repo about it: Improve usability of doxmlparser doxygen/doxygen#8848
• The new API overview page points to the doxygen documentation, not for any RST that may exist for it. Since the page now comes from doxygen, we could a) add a new xrefitem tag to reference it, but then we'd have doxygen pointing to RST and RST pointing to doxygen, which could be an issue; or b) have another file to map RST pages for some doxygen groups, but it would be another burden to maintain. Any thoughts about this?

Fixes #50922

please revisit

[nordicjm]

In the current output, the list is just unusable, who's going to look at this https://builds.zephyrproject.io/zephyr/pr/61994/docs/develop/api/overview.html through 625 rows of APIs to find an API to use? The existing documentation has 94 so the table size has jumped 7 times

[henrikbrixandersen]

In the current output, the list is just unusable, who's going to look at this https://builds.zephyrproject.io/zephyr/pr/61994/docs/develop/api/overview.html through 625 rows of APIs to find an API to use?

I agree. Having this list in our documentation adds no real, user-oriented value to the project.

[gmarull]

In the current output, the list is just unusable, who's going to look at this https://builds.zephyrproject.io/zephyr/pr/61994/docs/develop/api/overview.html through 625 rows of APIs to find an API to use? The existing documentation has 94 so the table size has jumped 7 times

Indenting with -

[gmarull]

In the current output, the list is just unusable, who's going to look at this https://builds.zephyrproject.io/zephyr/pr/61994/docs/develop/api/overview.html through 625 rows of APIs to find an API to use? The existing documentation has 94 so the table size has jumped 7 times

Versions also seem to be part of the (0.1.0, 0.8.0 and 1.0.0) set only. I am not sure how has this even decided. This doesn't make any sense.

[nashif]

Versions also seem to be part of the (0.1.0, 0.8.0 and 1.0.0) set only. I am not sure how has this even decided. This doesn't make any sense.

this is explained in the overview, added another note now. The version numbers are based on current life cycle status as we have it documented for some of the APIs right now. Those versions will change as the API evolves over time.

[nashif]

Indenting with -

yes, not my favorite as well, probably there is a better way to display a tree, suggestions welcome. Change to _ now, looks a bit better.

[nashif]

In the current output, the list is just unusable, who's going to look at this builds.zephyrproject.io/zephyr/pr/61994/docs/develop/api/overview.html through 625 rows of APIs to find an API to use? The existing documentation has 94 so the table size has jumped 7 times

"It is what it is" This is how many APIs we have. If you are interested in 1 API, you can search for it in the table. The table loads juist fine for me.
The fact that the existing list was short is because it was unmaintained and incomplete. This is what we are trying to sovle with this PR among other things.

[jukkar]

I don't think this should have any version information, as it is an umbrella entry without anything in the group. All the other network related groups are children of this "networking" group but it does not make them stable. If one looks at the generated documentation list, it gives an impression that all the network APIs are v1.0.0 which is not the case.

[kartben]

Indenting with -

yes, not my favorite as well, probably there is a better way to display a tree, suggestions welcome. Change to _ now, looks a bit better.

as a quick hack, I am guessing &nbsp would achieve the same goal without being visible

[nashif]

as a quick hack, I am guessing &nbsp would achieve the same goal without being visible

I tried this, did not work.

[edersondisouza]

In the current output, the list is just unusable, who's going to look at this https://builds.zephyrproject.io/zephyr/pr/61994/docs/develop/api/overview.html through 625 rows of APIs to find an API to use? The existing documentation has 94 so the table size has jumped 7 times

Indenting with -

I had a version that indented with spaces, but for HTML only, not for PDF - but the feedback was "need to work with PDF". Sphinx is quite keen on removing whitespaces...

[carlescufi]

The overall idea and implementation is fine. I am not particularly a fan of versioning individual APIs but I'll take it as a means to help our users.

But I completely disagree that we should sacrifice the cleanliness of the HTML build to improve the .pdf one. I think the HTML one should come first, and those _ are just very distracting and reflect poorly on the quality of our doc. I suggest @edersondisouza reverts back to spaces.

[nashif]

But I completely disagree that we should sacrifice the cleanliness of the HTML build to improve the .pdf one. I think the HTML one should come first, and those _ are just very distracting and reflect poorly on the quality of our doc. I suggest @edersondisouza reverts back to spaces.

yes, I am also fine with that, the indentation and table looks bad with the '_'

[edersondisouza]

Ok, found a way to indent with spaces that seems to work both with HTML and PDF.

[nashif]

"\U000000A0", nice

[carlescufi]

LGTM now, thank you!