[DISCUSSION] Set up documentation/website generator

[lidavidm]

There's already some question of where to put documentation: #24 (comment)

Some candidates:

• Doxygen handles C++ nicely and can scrape docstrings. It can also generate a website, not just API docs, and accepts a limited amount of Markdown. IMO, however, it doesn't look very pretty (though you can theme it).
• Sphinx while primarily used for Python can also handle C++ and is easily extensible. It does not scrape docstrings. It can render Doxygen-generated docstrings via a plugin but IMO this does not look very nice, loses some of the structure that Doxygen has, and the plugin seems to be minimally maintained/unmaintained (for a while it required a rather outdated version of Sphinx). It can render Markdown through a plugin (though it will be Sphinx-flavored Markdown).

We could also go with separate documentation/website generators, in which case we could pull in Jekyll/Hugo/Quarto/Sphinx/[insert your favorite yak shave of choice here].

Has anyone worked with any other tools?

[wgtmac]

I'm not an expert so I asked ChatGPT to search other alternatives for me:

Name	Pros	Cons	Links
MkDocs with Doxybook2	• Modern, clean look • Fast build times • Markdown support • Excellent search functionality • Mobile-friendly • Easy customization • Active community	• Requires Doxygen as intermediate step • Additional setup complexity • Two-step build process	• MkDocs • Doxybook2 • Material theme
DocFX	• Modern Microsoft-backed platform • Multi-language support • Clean design • Good search capabilities • Cross-platform	• Steeper learning curve • More complex setup • Originally designed for .NET	• DocFX • DocFX Guide
Standardese	• Modern C++-specific • Clean output • Accurate C++ parsing (libclang) • Markdown support • Standard C++ documentation style	• Less mature than alternatives • Smaller community • Limited customization options	• Standardese GitHub
cldoc	• Clean, modern output • Accurate C++ parsing (Clang) • Good C++11 support • Simple configuration • Static HTML generation	• Less active maintenance • Limited themes • Basic feature set	• cldoc GitHub
Natural Docs	• Language-agnostic • Natural readable format • Modern output • Good organization • Active maintenance	• Less C++-specific features • Limited API documentation features • Less flexible customization	• Natural Docs • Getting Started

[lidavidm]

ChatGPT misses again!

• Doxybook2 is no longer maintained.
• docfx has no C++ support. We'd have to manually convert Doxygen output.
• Standardese, maybe. It hasn't released in about ~4 years.
• cldoc last released in 2018.
• Natural Docs, maybe, but it requires Mono on Linux/macOS. And is mostly focused on C# and doesn't claim full support for C++.

[wgtmac]

Doxygen might be the best option from all the information we have so far :)

[lidavidm]

At the very least, most other solutions will use Doxygen as a base so I'll try and set it up

[Fokko]

I don't have any opinion on the C++ documentation generation, but we use mkdocs at PyIceberg, and it works really well: https://github.com/apache/iceberg-python/tree/main/mkdocs

[pitrou]

How does mkdocs compare to Sphinx? Sphinx really has excellent cross-referencing capabilities (to API docs, to glossary, to other pages, to index references, even to other Spinx docs).

[Fokko]

@pitrou It is pretty similar, mkdocs feels a bit more modern to me. Referencing the Python docs works pretty well: https://py.iceberg.apache.org/reference/pyiceberg/io/

[lidavidm]

How does it work for C++ though? I see a few random plugins (like cxxdox) but I'm not confident in them vs Doxygen. (I also don't see from a bit of searching how mkdocs handles the equivalent of a Sphinx :cpp:class or :py:meth: etc. which is one of the best features of Sphinx for me.)