Set up source-code documentation framework

[daphne-eu]

In GitLab by @pdamme on Mar 17, 2021, 19:40

The documentation of the prototype should ideally reside in a top-level directory doc. We need to set up the processes to generate the qualifying parts of the documentation and must define how to write additional "manual" documentation.

It will likely include:

• manually written overview pages, tutorials, etc.
• source code documentation generated via doxygen or similar
• DaphneIR documentation generated via MLIR/LLVM's tablegen
• ...

[m-birke]

please assign to me

[pdamme]

Thanks for having a look into this, @m-birke! That will definitely bring the project forward.

For everyone interested: We had a short conversation today on how to improve the DAPHNE documentation by automatically generating it (e.g. from the existing Markdown files and the source code comments) and using modern documentation themes (with great usability features).

[m-birke]

More thorough feature description:

1. Documentation from source code for each part of a library (namespaces, classes, etc.) and integrate it into the reference
2. Links between items in the reference and to outside content.
   • For example if a function returns a particular type, the user can click on that type to go straight to the documentation for it.
3. Exclude private class members, selected types, or entire namespaces that are mere implementation details and not public API.
4. Combine API documentation (cpp + Python) with conceptual content such as overviews, build instructions, or examples
   • markdown
5. End product is one cohesive package that can be served on the web.

Tools

Name	URL	Comment
Hyde+Jekyll	https://github.com/adobe/hyde	Does not use inline documentation, but extra files
Standardese	https://github.com/standardese/standardese	Seems fine. No frequent development
Doxygen+Sphinx		Recent developments! cpp and Python stream can be joined. No common intermediate repr. Make use of vibrant Python community regarding themes.
hdoc	https://hdoc.io/	Seems most modern. Account necessary + API KEY usage

Some web reference:

https://slint-ui.com/blog/documentation-tools-for-cpp-libraries

[corepointer]

I believe this issue was resolved when merging #550. Reopen if this is not the case.

[pdamme]

Actually, this issue was (also) about an automatically generated C++ and Python API reference documentation of the DAPHNE source code itself (DAPHNE system and DaphneLib). Such an API reference could make life easier for developers working on the DAPHNE source code. For instance, they could quickly find out which namespaces, classes, functions, etc. there are and what they mean. Furthermore, tools that generate such documentation (e.g., doxygen) can also warn about undocumented or inconsistently documented source code entities, which could "motivate" us to put more effort into the documentation of the source code itself.

550 was mainly about the generated HTML pages for user documentation and hand-written developer documentation. However, as generated source code documentation is still missing, I would reopen the issue (and have just adjusted the issue name).