Documentation UX revamp and internal CMake docbuild restructuring

[Helveg]

This PR aims to present users with a simple streamlined approach to building the documentation. A user requests which documentation they are interested in by toggling CMake flags for documentation types aimed at certain target audiences, and CMake figures out which documentation targets need to be configured for that. Documentation is generated either implicitly upon installation (make install), or explicitly by using make docs, or any of the subtargets, but the subtargets aren't considered public features.

Documentation targets are:

• sphinxdocs: Uses Sphinx to generate the html documentation, and lots of stuff happens, see comment in code.
• doxygendocs: Uses Doxygen to generate the dev docs.
• There is a legacy block for SLI docs, that I didn't refactor as SLI is removed soon.

Documentation flags are:

• with-userdoc: Toggles the user documentation, on by default.
• with-devdoc: Toggles the developer documentation, off by default.

User stories

• I want to install NEST
  • Userdocs are generated and installed along with the NEST library
• I want to turn off this documentation
  • I pass -Dwith-userdoc=OFF
• I want to have developer documentation
  • I pass -Dwith-devdoc=ON
• I want to build the docs, not NEST
  • I use make docs instead of make install

closes #1905

[Helveg]

Since building the user documentation brings in a lot of additional build time and dependencies, that need to be installed from different source (apt, pip, built from source, ...) and the ReadTheDocs documentation is more accessible, and more convenient, we opted to turn off the local build of the documentation.

[jessica-mitchell]

@Helveg thanks for this PR
the docs seem to build correctly but there is this error at the end of the for userdocs build:

cmake -Dwith-userdoc=ON ~/Work/repo/nest-simulator/
make docs

the devdoc flag does not elicit any errors.

[Helveg]

I can't reproduce this. Do you have the proper file permissions to execute resolve_includes.py; is it executable? If I'm interpreting the image correctly, it looks like it's trying to run resolve_includes.py as a shell script, which is not something that happens for me, it should probably be ran using python, maybe somehow Python_EXECUTABLE was empty, we can look at it together.

[jessica-mitchell]

thanks @Helveg I just have a few changes

[jessica-mitchell]

thanks lgtm!