How the API documentation is generated?

[LumineBot]

First of all, I'm sorry that this is not the question related to the library itself, but rather the documentation inside this repository. Your documentation look awesome and I would like to build similar thing for my private personal project with mkdocs.

But when I see the code, I couldn't find anything specific on how the API documentation is generated from the source. So.. does the API documentation here is generated by mkdocs and/or its plugin from the source documentation? Or is it completely written and maintained by hand?

[nlohmann]

Yes, the docs are created with mkdocs and https://squidfunk.github.io/mkdocs-material/.

To build, run the following in the docs/mkdocs folder:

make install_venv
make serve

This will start a local web server and you can visit http://127.0.0.1:8000/ to browse the documentation.

The relevant Markdown files are in docs/mkdocs/docs.

Let me know if you need any support.

[LumineBot]

Hi @nlohmann thank you for the answer!
But that's not what I meant. What I was wondering is that all of these markdown files in this folder:
https://github.com/nlohmann/json/tree/develop/docs/mkdocs/docs/api

are generated from the source files comments or are they manually typed by hands?

[nlohmann]

Oh sorry. Yes, they are created manually.

[nlohmann]

(I struggled with Doxygen and related tools for quite a while since I wanted to combine similar API functions, but always failed. In the end, I spent less time actually writing text to support users than fighting tools to read information from the source code. Eventually, writing Markdown is much easier and also helps you to focus on the user's perspective who probably never look at the code.)

[LumineBot]

Thanks for your answer and insight! Now I think about it, I believe writing it manually is better than a generated docs, easier to convey the connecting dots between classes and/or usages.