source: bsp: Reorganize manual index

[mschwan-phytec]

Add an extensions for numbering sections in a custom way. The uppermost section title is not numbered, only subjacent ones. This allows for putting an unnumbered BSP manual title directly in the related document and still have the rest of the content with numbered sections.

Reorganize the BSP manual index. Add the Yocto manifest name as the title for each BSP release, so it is displayed at the top of the document. Using the custom sectnum extension, this now allows to directly reach a BSP manual's content by navigating the left side-bar.

This also reduces the number of required mouse clicks to reach a manual, improving the accessibility. It is also now quicker and easier to overview the different phyCORE and phyFLEX products and their associated BSP manual.

As a consequence of consistent BSP manual naming, the "HEAD" documents are now called the same way as the Yocto manifest name, meaning they use the ".y" suffix in their release name. This should make is more clear for customers and users of our BSP, that these manuals are directly related to the development manifest with ".y" suffix in their name.

In the process, some unneeded platform-specific index files were removed.

Update and correct some y-manifest names.

Sort the SoC platforms alphabetically.

This is a preview of the changes:

Notice the different overview of the sidebar and direct access to BSP manuals.

[ymoog]

I liked the previous tree where a different page would be displayed depending on the name selected in the menu on the left. I see the ship has already sailed regarding the release notes, where it does not matter on which SoC you click, the same page will always be displayed.

[mschwan-phytec]

I liked the previous tree where a different page would be displayed depending on the name selected in the menu on the left. I see the ship has already sailed regarding the release notes, where it does not matter on which SoC you click, the same page will always be displayed.

I also noticed and thought about this. I considered two points here:

• What is easier/faster to navigate as a user?
• What is simpler to organize/maintain in the source code?

To maximize both these parameters I think we would simply put all platform manuals in a single index file. This would allow users to jump to manuals with less clicks, as they are not divided for each platform. And we have less files to maintain in the source code.

The currently proposed solution in this PR is a mix of both worlds. Here, index files are organized for each SoC-family. So there is some separation, but less-so than previously, that's for sure.

Do you have any further thoughts on this?

[BHahn42618]

I agree with Yannic. I would also prefer to only get the phyCORE-i.MX 8M Plus manuals shown when I click on "phyCORE-i.MX 8M Plus" and not all imx8 manuals. However I do like, that now only the Manual names are shown then and not all headings in the manual.

[BHahn42618]

I noticed, that for phyCORE imx8mp, the sorting is a bit off now with the new naming scheme after the manifest. I think we should adjust the sorting here to keep it alphabetically. The current sorting is:

BSP-Yocto-NXP-i.MX8MP-PD26.1.y
BSP-Yocto-Ampliphy-i.MX8MP-PD24.1.y
BSP-Yocto-Ampliphy-i.MX8MP-PD24.1.2
BSP-Yocto-NXP-i.MX8MP-PD24.1.1
BSP-Yocto-Ampliphy-i.MX8MP-PD24.1.1
BSP-Yocto-NXP-i.MX8MP-PD24.1.0
BSP-Yocto-NXP-i.MX8MP-PD23.1.0
BSP-Yocto-NXP-i.MX8MP-PD22.1.2
BSP-Yocto-NXP-i.MX8MP-PD22.1.1