Dear Urs, it’s great that you found time for that. It looks nice and I think MkDocs is a good choice (would have been my first choice, too).
While speaking about documentation, I very much like this approach: https://www.divio.com/blog/documentation/ Some nitpicks from me: - Should everyone see the "Edit this page" pencils? - Those links are broken for me - If you descend into a package documentation, "Home" will not bring you to openlilylib.org but to the page of the package. While that is probably a consequence of your fourth bullet point, I find it confusing. - Do you like the brown color? > * Each sub-site is maintained in a separate Git repository and > included as a Git submodule, so it should be straightforward to > manage independent authoring of the documentation by the respective > package maintainers. While this theoretically makes sense to separate the packages' documentation, I would run from git submodule. But perhaps your use case is easier than where my experience comes from and you can still change that decision later in case it makes things easier. > What I really *want* to have but have no idea so far how to achieve is > additional code/API documentation retrieved from the actual source > files. There should be a tool to retrieve that from comments (or actual > signatures?), What do you mean by signatures? IMHO, this makes sense for "reference-type" documentation in addition to other parts of the documentation (cf. link at the top). Cheers, Joram
