zephyrproject-rtos
doc: boards: extensions: introduce zephyr:board role and directive
https://builds.zephyrproject.io/zephyr/pr/79994/docs/boards/seeed/wio_terminal/doc/index.html https://builds.zephyrproject.io/zephyr/pr/79994/docs/contribute/documentation/guidelines.html#boards
A new zephyr:board:: Sphinx directive allows to flag a documentation page as being the documentation for a specific board, allowing to auto-populate some of the contents, ex. by adding a board overview à la Wikipedia, and later things like supported HW features, a ready-to-copy-paste example of how to build Hello World, etc.
A corresponding :zephyr:board: role allows to link to a board doc page.
@kartben unrelated to this PR, but, could we make header less cluttered?
The "Open on github" and "Report an issue with this page" could simply be icons IMO, with the text in a tooltip. Of course accessibility needs to be verified.
@kartben unrelated to this PR, but, could we make header less cluttered?
Agreed -- I too found it particularly striking when making the screen capture :) Will go for text-less version of the GH buttons and will try to find a way to have ellipses in the breadcrumb
Just pushed a fix for a nasty bug that was causing Sphinx logs to be silenced - whoopsie.
Great stuff can't wait to see how this renders in the pdf.
We don't include boards in the PDF 😝
Had to push one more commit to clean up 3.7 release notes re: Sphinx lint.
Just like code samples, boards are now referenced using a dedicated role and not the generic :ref: anymore so this requires updates tree-wide, and I deliberately hadn't made a pass on past release notes regarding Sphinx linting as I didn't want to "touch" them unnecessarily (but since the lint errors were actual bugs causing bad rendering, I probably should have...)
LGTM. It would be nice to start a mass cleanup of board pages. They contain tons of redundant information that just increases doc build time.
@gmarull this will be incremental and take a lot of time but... yes, definitely -- e.g. https://github.com/zephyrproject-rtos/zephyr/pull/80048