doc: add RIOT root doxygen example path

[kfessel]

Contribution description

add RIOT root to Doxygen example path
and include some Readme.md with their respective doc.txt

sadly we can't use @includedoc or @include{doc} until Doxygen 1.9.2
see doxygen/doxygen#8395

Testing procedure

read
and
check circleci: doc-build artifact

eg
https://15379-7370241-gh.circle-artifacts.com/0/doc/group__pkg__u8g2.html
vs
https://doc.riot-os.org/group__pkg__u8g2.html

Issues/PRs references

#10815

[chrysn]

I generally appreciate rendering more and more of what we have in documentation to where we advertise that our documentation is.

The linked output currently has the markdown included as preformatted text rather than inlined and parsed.

Why the split of doc.txt and README.md for the uwb? I think this would perfectly well as one file, given suitable markup.

Similarly for the others: Why is this split into two files in the first place?

[kfessel]

As you can see with the UBW it previously was part of the doc.txt (empty README.md should be considered an achievement) (at the same time it was unrenderd) - (and the writer did not care or he like how it was more readable)

.md files are much easier to write and to read that these .txt (personal opinion)

README.MD further have the advantage that they are automaticaly render by github

with doxygen 1.9.2 @include{doc} should work as it should (sandly with 1.9.1 it does not parse markdown -> generates an utter mess)

https://doc.riot-os.org/group__pkg__uwb__dw1000.html
https://15379-7370241-gh.circle-artifacts.com/0/doc/group__pkg__uwb__dw1000.html
https://github.com/kfessel/RIOT/tree/p-set-doxygen-example-path/pkg/uwb-dw1000

[chrysn]

.md files are much easier to write and to read that these .txt (personal opinion)

Yes, it gives syntax highlighting in most editors (for as good as it gets with the markdown flavors and the extras added by doxygen).

README.MD further have the advantage that they are automaticaly render by github

Is it possible, with the recent Doxygen releases this needs, to use the .md files for all our doc needs then? (Ie. also put the grouping stuff in there). Having information spread (content vs structure) and duplicated (title) between two files sounds suboptimal. (I think we can afford having some Doxygen artifacts on the Github rendering of the .md files).

[kfessel]

at least a *.md wild card in doc/doxygen/riot.doxyfile:794 FILE_PATTERNS
creates a very messy doc
maybe including doc.md and rewriting (remove that c-comment decoration would be a good solution)

just remembering i also tested that it generated a smaller mess (but may be i used the doxygen grouping tags wrong)
see #17575 circle-ci build artefakt: https://15407-7370241-gh.circle-artifacts.com/0/doc/index.html

[kfessel]

with doc.md

there isn't anything in that doc
https://15407-7370241-gh.circle-artifacts.com/0/doc/md_pkg_uwb-dw1000_doc.html
-> grouping works
https://15407-7370241-gh.circle-artifacts.com/0/doc/group__pkg__uwb__dw1000.html
(same behavior for current 191 doxygen)

[OlegHahm]

Is there an estimated release date for doxygen 1.9.2? Would it make sense to wait a little bit?

[OlegHahm]

And wouldn't #17575 be the preferred solution?

[waehlisch]

Is there an estimated release date for doxygen 1.9.2?

?? "The latest version of doxygen is 1.9.3 (release date 31 december 2021, updated 3th of January 2022)." https://www.doxygen.nl/download.html#srcbin

[kfessel]

#17575 would be nice but it does not work as expected see #17572 (comment) , i am not sure if there is a doxygen version where that is fixed

1.9.2 (even 1.9.3) is already released but neither in our circleci nor is it used to build doc.riot-os.org

• as doc: doc.riot.org and circle-ci use different doxygen versions doxygen 1.8.17 vs 1.9.1 #17580 shows they have diverged a bit making evalution of changes in the circleci artifact less useful

[OlegHahm]

Sorry for the late response: apparently I've disabled too many of the GitHub notifications.

Regarding the doxygen version: I was referring to the release of 1.9.2 as part of Debian. Even unstable still contains doxygen 1.9.1.

Given the problem with #17575 I would agree with merging this PR for now and give #17575 another try once a newer doxygen version is available.