documentation: better end-user documentation and learning resources

[jia200x]

Description

After the last monthly discussion on better documentation efforts, it came the idea of improve several topics and maybe add stuff like openthread.io:

• Mantain an up-to-date webpage for each board, with better documentation on specific configurations, pinouts, etc.
• Add some guides and better end-user documentation (#5434).

I also take the opportunity to add additional ideas. Feel free to add more and discuss about these topics!

RFC/Ideas

• [x] Move board specific documentation to Doxygen: #8516 (@smlng + @aabadie)
  • [x] Where to put the files? boards/<board_name>/doc?
• [ ] Generate board/cpu-specific doxygen pages with a script (@bergzand)
• [ ] Add pinouts of peripherals
  • [ ] Generate pinout from code?
• [ ] Codelabs
  • [ ] RIOT-OS/Tutorials in Codelabs? (@miri64)
• [ ] End User/Developer guides (@emmanuelsearch )
  • [ ] RIOT fundamentals tutorial (like Angular's Tour of Heroes)
  • [ ] Migrate content from Wiki (partly in #8516)
  • [ ] Extend Doxygen? Static site with embedded Doxygen doc? (like openthread.io)
• [ ] Move @defgroup directives to doc.txt instead of header files
• [ ] Add categories to Doxygen modules
  • [ ] Serializations (#9840)
  • [x] Math (#9842)
  • [ ] Power management
  • [ ] Hashes (#9858)
  • [ ] Memory Management
  • [ ] Debugging
  • [ ] Data structures
  • More to be added...

Related issues

8302, #7998, ~#7001~, #5434

[bergzand]

I would like to suggest to generate a number of board/cpu-specific doxygen pages with a script.

For example, a table of boards with the CPU model, type and supported peripherals could be generated from the board makefiles using the CPU_MODEL, the FEATURES_MCU_GROUP and the FEATURES_PROVIDED variables.

This way the documentation is automatically synced with what the build system provides for the platform. No manual updates anymore :)

A step further would be to generate an overview of pin mappings from the configured peripherals as stated above.

[Josar]

@bergzand i just wrote to the mailing list and was suggestig something related.

Did you thing about how this could be done or implement something in this regard?