CMake documentation is currently a mess

I was trying to make the website look a bit nicer and make the documentation look how it used to look in version 2.7, however, there are several problems.

We use a hard coded script to generate the build system documentation. If you miss any of the hard-coded formats, the script does not work. We have missed quite a lot of them since version 2.7 and its documentation is not rendered anymore in the online sphinx documentation:

• The licenses added one blank line between the licenses and documentation. This was not taken into account by the script.
• At some point some of us started to use multi-line comments to document things. This also does not work.
• Some functions and variables are documented with the wrong keywords, e.g. cmake:function:: instead of cmake_function::. This also does not work.
• The website was also not updated to build the newer versions since v2.7, so users only have access to a very old documentation, or a broken one.

This is not to blame anyone who contributed, but to begin a discussion on a better way to document these files given the current form is clearly not maintainable. I think is too much work through versions 2.8, 2.9, and 2.10 and fix them, but it would be nice to agree on a path forward. I would even suggest that we do not expose the online documentation for those broken versions until is fixed, otherwise, it's more confusing than helpful.

Also, now that we are finishing the transition period for a more modern CMake (with proper targets), it would be nice to have a new documentation on how that's supposed to work.