Consolidate documentation

[nlohmann]

This PR consolidates two streams of documentation: Doxygen-style comments in the source code and the newer MkDocs-based Markdown documentation in folder doc/mkdocs. Both documentations diverged over time, and since we reached the limits of what Doxygen can do, we decided to drop Doxygen and go all-in on MkDocs. As a result, we removed all Doxygen-style comments for the public API and updated/fixed the MkDocs accordingly. The result is a much cleaner documentation that documents all overloads of functions with the same name on the same page.

In particular:

• move images from doc/images to doc/mkdocs/images
• fix typos in README and comments
• remove Doxygen files and code comments
• add README how to build documentation locally
• remove Wandbox online code examples
• add more examples
• overworked documentation of public API (https://json.nlohmann.me/api/basic_json/)
• documented all deprecations and added hints how to replace deprecated calls
• added documentation linter to enforce standard section naming and ordering
• remove Doxygen documentation from public API and added links to online pages
• adjusted parameter namings to those of the documentation

[coveralls]

Coverage remained the same at 100.0% when pulling 638104f on clean_doxygen into 825d323 on develop.

[gregmarr]

Assuming I understand this right and the documentation is still in the distribution, just not in the header file, should the comment with the link to the latest documentation also contain the path to the documentation for this version? I still see utility in being able to see the documentation as it was written at the time that the version I'm using was released. Will the documentation site still contain the documentation for any functions that are removed with v4 comes out and several of the deprecated functions are removed?

[nlohmann]

Assuming I understand this right and the documentation is still in the distribution, just not in the header file, should the comment with the link to the latest documentation also contain the path to the documentation for this version? I still see utility in being able to see the documentation as it was written at the time that the version I'm using was released. Will the documentation site still contain the documentation for any functions that are removed with v4 comes out and several of the deprecated functions are removed?

Good point!

The motivation for this PR is the observation that the documentation in the code and that in the docs folder start to diverge. Furthermore, Doxygen is so inflexible that the current output is ugly and needs a lot of repetitions in the code. That said, I want to drop Doxygen.

As the docs folder is tagged together with the sources, it should be able to get the documentation for the future versions. What do you think? Is this sufficient?

Maybe (?) there is also a way to have URLs like https://json.nlohmann.me/v3.10.3/api/basic_json/accept/ or so that contain the documentation for a specific version.

[gregmarr]

I agree that Doxygen isn't the greatest. :)

This may not be sufficient for people that only use it as a submodule tagged to a specific commit. The direct file links would still be helpful there, and would also make it easier for maintainers to update the docs when they make changes. Maybe it would be enough to have a single comment at the top that describes how to convert from a URL to docs folder location.

[akapocsi]

@nlohmann The consolidated docs looks great.

Just wanted to point out that there are some stale links/references to the doxygen docs in the main README: https://github.com/nlohmann/json/blob/develop/README.md?plain=1#:~:text=doxygen

[nlohmann]

Thanks @akapocsi! Fixed in eb21824.