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.

Special Jobs

build

The 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

The 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.

Implementation Highlights

Commit Credentials

Commit to the aforementioned aggregated repository is allowed by a personal access token that is set up in that repository. The value of the token is stored as a protected variable available to the docs repository.