Add generator for modern buildsystem documentation

Summary

The buildsystem documentation generator does not support multi-line comments, rst systax and modern CMake documentation commands as used in CMake itself. This MR adds some functionality and redirects to a python module to do the rest.

Discussion

How to specify the python package dependencies for the buildsystem documentation generator? The necessary requirement is sphinxcontrib-moderncmakedomain. Should this be put into the dune.module file? Or into the pyproject.toml file?

TODO

• Squash the Commits
• Add Changelog entry
• Improve the table of content generation

added buildsystem label

added 1 commit

• d9853b95 - Update extract_cmake_data script

Compare with previous version

At the moment py project.toml is autogenerated by the dunepackaging script and only used for the packaging for pypi. So that would not be the right place in the current context. Does the buildsysysten docu build use the dune internal env? Everything listed in dune.module is installed there (and added to the pyproject.toml for packaging).

added 1 commit

• 6944f882 - Add sphinx moderncmakedomain to repository

Compare with previous version

added 1 commit

• c30603cd - Remove print statement that was introduced for debugging

Compare with previous version

added 1 commit

• 8b8a34c7 - Add copyright notice

Compare with previous version

added 1 commit

• a0bb98c4 - Add source url

Compare with previous version

added 61 commits

• a0bb98c4...a85c317c - 58 commits from branch master
• ea46c899 - Update extract_cmake_data script
• 5a48e367 - Add sphinx moderncmakedomain to repository
• 895e2a6c - Improvement of the documentation of dune_add_library

Compare with previous version

changed the description

resolved all threads

The modern cmake documentation is IMHO more readable than the old one. Currently this MR preserves the old documentation generator. Maybe we could transform the old documentation into the new style and then remove the old cmake documentation generator.

added 1 commit

• e33efa8c - Add explicit links to documentation in toctree

Compare with previous version

@dominic You have implemented, together with @joe, the buildsystem documentation (as far as I can tell from the git log) Instead of manually extracting all the cmake doc from the files, I would go towards a sphinx domain, using the official cmake implamentation. Do you have any suggestions how to properly extract commands and modules into the TOC?

I like this MR and I agree that including the Sphinx dependency is valid and the right choice. I tested it for dune-common. Squashing is not required, the commits don's have changes that are reverted later and the commits are logical units. Just add the change log.

mentioned in issue #345

mentioned in issue #402