Improve project and doxypress documentation

[salkinium]

Ok, so I looked at the docs and I discovered significant issues, a lot of missing classes and wrong module names etc.
This fixes the doxypress @ingroup tags and some minor coding style issues.
I also added reference docs for all targets grouped by platform and family and reference docs for all configurations, to make both of them discoverable via the website.

• Correct doxypress group in all modules.
• Link occurences of modm:module and modm:module:option to the modm_module group.
• Enforce deprecations on release/ branch.
• Remove useless FAT driver.
• Implement Doxypress macros (does not work correctly).
• Remove header source code inclusion to reduce time and space.
• Remove namespace tab, as it contains no significant information.
• Remove modm::dummy function in favor of lambdas.
• Add modm.io/reference/config/modm-config docs
• Add modm.io/reference/targets that lists all target strings explicitly and documents the target /revX mechanism.
• Made the absolute https://modm.io URLs in the README relative for the mkdocs, so that mkdocs serve links to the local URL.
• Keep mkdocs and mkdocs-material tools up-to-date in CI.
• Link board table to the configurations, rather than the board modules so the revisions are discoverable.
• Removed wrong use of modm_always_inline
• Refactored for consistent use of other attributes

I found several issues in Doxypress:

• Our pattern of struct driver that is inherited by class Driver : public driver is invisible, because Doxypress apparently does not respect letter case and merges both structs into one class.
• @ingroup does not work across namespaces, so you need to close the group before a new namespace starts, then open the same group inside that namespace, then close it before it ends, then open the namespace after it has been closed. This has been a significant issue for our Board namespace and has been fixed, but it's ugly.
• Expansion of macros with arguments does not expand the arguments, it just prints the expansion. So we have a lot of x_t = Flags32<x> because MODM_FLAGS32(x) is not expanded correctly. Same with EXTERN_FLASH_STORAGE(x), which is used by the ui/display/image files.
• There are some cases where the namespace is lost, ie. classes are placed outside of a namespace. It can be worked around by closing the namespace and opening it before the class (encountered in modm::platform::GpioConnector with the modm::platform::detail namespace just above it).
• There are some cases where the class is just invisible and nothing I tried could fix it (specifically modm::platform::GpioPort on STM32 is lost).

[rleh]

Our pattern of struct driver that is inherited by class Driver : public driver is invisible, because Doxypress apparently does not respect letter case and merges both structs into one class.

I noticed that too. I'm not sure it's always been that way.
Creating an minimal example and reporting to the copperspice people is on my to-do list...

Maybe that problem would disappear by switching to the libclang parser?
But:

"clang-parsing": true segfaults for me 🙀

[chris-durand]

I will review in the evening.

[salkinium]

I added target and config reference docs for the homepage.
You can download the test archive (here, but check for the latest job) and launch python3 -m http.server --bind 0.0.0.0 8000 inside it to check out the homepage.

[salkinium]

Here's what the target page looks like, I put the identifier schema in there for reference, and also grouped them by device name:

Target Page

Here is the config page with revisions. It's the same as the board module page, except with revision info and the configuration xml:

Config Page Disco-F469

[chris-durand]

Nice clean-up, thanks!

[salkinium]

I want to merge this tomorrow, so please review until then (or don't, if you trust me ;-)

[rleh]

I'll do a review tomorrow.

[rleh]

There are very few "wrong" ingroup commands using a small script:

ERROR: Probably a bad doxygen group ('driver_mcp23x17') in file 'src/modm/driver/gpio/mcp23_transport.hpp'.
ERROR: Probably a bad doxygen group ('driver_mcp23x17') in file 'src/modm/driver/gpio/mcp23_transport.hpp'.
ERROR: Probably a bad doxygen group ('platform_uart') in file 'src/modm/driver/io/terminal.hpp'.
ERROR: Probably a bad doxygen group ('platform_uart') in file 'src/modm/driver/io/terminal.hpp'.
ERROR: Probably a bad doxygen group ('driver_ea_dog') in file 'src/modm/driver/display/st7036.hpp'.
ERROR: Probably a bad doxygen group ('driver_ea_dog') in file 'src/modm/driver/display/st7036.hpp'.
ERROR: Probably a bad doxygen group ('driver_ea_dog') in file 'src/modm/driver/display/st7565_defines.hpp'.
ERROR: Probably a bad doxygen group ('driver_ea_dog') in file 'src/modm/driver/display/st7565_defines.hpp'.
ERROR: Probably a bad doxygen group ('driver_ea_dog') in file 'src/modm/driver/display/st7565.hpp'.
ERROR: Probably a bad doxygen group ('driver_ea_dog') in file 'src/modm/driver/display/st7565.hpp'.
ERROR: Probably a bad doxygen group ('driver_i2c_eeprom') in file 'src/modm/driver/storage/cat24aa.hpp'.
ERROR: Probably a bad doxygen group ('driver_i2c_eeprom') in file 'src/modm/driver/storage/cat24aa.hpp'.
ERROR: Probably a bad doxygen group ('board_black_pill_f401') in file 'src/modm/board/black_pill_f411/board.hpp'.
ERROR: Probably a bad doxygen group ('board_nucleo_g474re') in file 'src/modm/board/nucleo_g431rb/board.hpp'.
ERROR: Probably a bad doxygen group ('board_nucleo_g474re') in file 'src/modm/board/nucleo_g431rb/board.hpp'.
ERROR: Probably a bad doxygen group ('board_nucleo_l552ze_q') in file 'src/modm/board/nucleo_l552-ze-q/board.hpp'.
ERROR: Probably a bad doxygen group ('board_nucleo_l552ze_q') in file 'src/modm/board/nucleo_l552-ze-q/board.hpp'.
ERROR: Probably a bad doxygen group ('architecture_1_wire') in file 'src/modm/architecture/interface/one_wire.hpp'.
ERROR: Probably a bad doxygen group ('math_matrix') in file 'src/modm/math/lu_decomposition.hpp'.

Found 19 suspicious doxygen groups in 727 ingroup commands.

Maybe we could add the script to the CI...? (But I don't know what is the best way to handle the false positives.)

#!/usr/bin/env python3

import re
import glob
from pathlib import Path

files = list(Path("src/").glob("**/*.hpp")) + list(Path("src/").glob("**/*.cpp"))
regex = r"[\\@]ingroup\s+modm_(?P<groupname>[0-9a-z_]+)"
error_counter = 0
ingroup_counter = 0

for f in files:
    for l in open(f, "r"):
        match = re.search(regex, l)
        if match:
            ingroup_counter += 1
            groupname = match.group("groupname")
            for s in groupname.split("_"):
                if s.rstrip("x") not in str(f):
                    print(f"ERROR: Probably a bad doxygen group ('{groupname}') in file '{str(f)}'.")
                    error_counter += 1

print("")
print(f"Found {error_counter} suspicious doxygen groups in {ingroup_counter} ingroup commands.")
exit(error_counter)

[salkinium]

I thought about writing a script that runs an lbuild simulation to get the build log and then checks that the ingroup maps onto the module that generated the file. That would give fewer false positives. But I'm not motivated to do that now, this was supposed to just be a "quick" fix that escalated as always 😜

[rleh]

Nice work, thank you a lot! 👍🏽