Switch to "Read the Docs" for automated documentation building and hosting (#143) · Issues · dorie / dorie

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.py and stop configuring it.
Create a readthedocs.yml configuration 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

### 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](https://readthedocs.org/), 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](https://docs.readthedocs.io/en/latest/index.html) 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](https://docs.readthedocs.io/en/latest/webhooks.html) 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](http://www.doxygen.nl/manual/starting.html) and stop using the DUNE Doxygen target.
   * Only use local paths in `conf.py` and stop configuring it.

* Create a `readthedocs.yml` [configuration file](https://docs.readthedocs.io/en/latest/config-file/index.html).
* Add [GitLab Environment](https://docs.gitlab.com/ee/ci/environments.html) for quickly referencing the docs.

### How to test the implementation?
CI pipeline passes. Docs are deployed to Read the Docs.

### Related issues
See #52

Edited Feb 11, 2019 by Lukas Riedel

Discussion
Designs

The one place for your designs

To enable design management, you'll need to meet the requirements. If you need help, reach out to our support team for assistance.