The docs Repository
The docs repository contains the general documentation of the All Scenarios OS
project. The documentation is normally written in reStructuredText, with an
important difference. Unlike in a regular project, the documentation here is not
standalone. Instead, the git repository contains symbolic links that are valid
when an entire workspace is constructed with
git-repo and the manifest repository.
This complicates the testing process and the deployment process, but allows the resulting documentation to span multiple repositories, permitting code and text to be conveniently changed in one go.
build job ensures that the documentation can be built with sphinx-build
without any warnings or errors. Apart from the complexity of setting up the workspace
as described above, it is fairly typical.
deploy job builds aggregated documentation view that is rendered at
https://allscenarios.readthedocs.org/. This job effectively constructs the
workspace as described above and then archives the entire documentation source code,
de-referencing any links that were followed to other repositories, and commits the
updated set of files to helper repository which is observed by readthedocs.
The helper repository is called allscenarios-readthedocs-aggregated. That repository contains a webhook, configured at the level of the GitLab project, which asks readthedocs to re-build the documentation.