While doxygen can handle markdown pages, support for it is very limited:
markdown pages can only be included as a whole page, they get an automatic
title (custom titles are possible but aren't standard markdown) and it's not
possible to use \subpage without messing with the markdown again. Any markdown
page will thus end up as separate item in the doxygen output, not really
suitable for generating a good page hiearchy.
Let's switch the tutorial to use doxygen directly instead of markdown, short
of using code/endcode instead of markdown's ``` there isn't that much
difference anyway but it allows us to structure things nicer in the online
docs.
Note that the order of the includes matters - that's how doxygen will sort
them. There is no specific structure other than the include order - one reason
why the headers are being changed. Without polluting the markdown files with
doxygen commands we cannot use \subpage, so all files convert to a regular
\page and are listed as flat hierarchy in the sidebar (and in Related Pages).
Changing the headers at least provides some visual grouping with comon
prefixes.
This tool detects and fixes common English spelling mistakes, with
generally very few mistakes.
Here is the command I used to generate this commit. There were a few
changes that had to be done manually, and of course adding the ignore
file:
```shell
codespell -I .codespell-ignore -x .codespell-ignore -w
```
I didn’t add it to the CI, but this would be a good place for it.
