Switch to "Read the Docs" for automated documentation building and hosting
Description
We currently use Netlify as our provider for the HTML online documentation. We only employ manual deploys right now, which means that we cannot make use of branch deployment, where every branch or tag gets a certain public URL. However, we cannot use the Netlify automated builds because or documentation build process requires CMake and Doxygen, both of which are not provided in the Netlify environment.
Read the Docs, on the other hand, offers a larger build environment which contains Doxygen (but not CMake). It features a clearer overview of the different versions of the documentation, and downloads of HTML or PDF files. See the Read the Docs docs for an example. I would like to switch to it and use its automated external build system to keep the documentation up to speed with the actual code development.
Proposal
Switch to Read the Docs!
Management tasks:
- Create a Read the Docs account.
- Add an outgoing webhook and register it with the account.
Repository tasks:
-
Make Sphinx and Doxygen documentation independent from CMake, such that running them does not require configuring the project.
- Create a complete Doxygen configuration file and stop using the DUNE Doxygen target.
- Only use local paths in
conf.pyand stop configuring it.
-
Create a
readthedocs.ymlconfiguration file. -
Add GitLab Environment for quickly referencing the docs.
How to test the implementation?
CI pipeline passes. Docs are deployed to Read the Docs.
Related issues
See #52