Add file markings to code blocks in the docs

[nmunnich]

We have a lot of code blocks in the docs. It would be useful if someone could go through and mark the blocks with title= where it could be helpful for readers to understand where the code blocks belong. Could be a useful task for someone who wants to become more familiar with the way things work.

[NewbiZ]

So I did go through all the code blocks and added titles whenever possible, but once done I pretty much hated the resulting documentation :)

Here is why:

• The vast majority of code blocks are either for your .conf or your .keymap. It is often pretty obvious where the code should belong since Kconfig and dts files look pretty different. So the titles ended up taking space while not providing much value.
• There are already quite a good amount of cases where the actual file where the code should belong is mentioned in the paragraph just above the code block, leaving little ambiguity. The advantage of using the paragraph above instead of the title of the code block is that you can link to the "Configuration" page to learn about all the places where the build system will look for .conf files.
• For the code blocks of files that do not belong to your config .conf / .keymap, these are often about your board definition, and I do not feel like titles such as app/boards/shields/<board>/<shield>.dtsi really helps.
• The "Development" section of the doc is essentially the only place where non-trivial (i.e. not .conf & .keymap) code blocks are used, but it is also the section where titles with filenames are provided for most code blocks.

What do you think? If you have examples of places where you think titles would be worth it, it will help to get a feel of what to do.

[nmunnich]

That's a fair point - for end-users it may indeed not be helpful. If you've already done the task, could you perhaps open a draft PR so that we can look at the end result? I think you're probably right in that the general configuration page along with everything in Development would be the places where the titles would be most useful.

[NewbiZ]

That's a fair point - for end-users it may indeed not be helpful. If you've already done the task, could you perhaps open a draft PR so that we can look at the end result? I think you're probably right in that the general configuration page along with everything in Development would be the places where the titles would be most useful.

Sure, I will push that tomorrow.

An alternative solution would be to do a bit of MDX to have some kind of tooltip in the filenames, this way we could at least provide some short description of possible filenames instead of config/<your_keyboard>.keymap.