Documentation and Other Static HTML

WWT documentation, such as the page that you’re reading right now, is version-controlled in the WWT GitHub organization just like any other project assets. The WWT documentation was historically split among several documents, and the current collection has synthesized many different materials, and so the number of repositories is substantial. For historical reasons, the names of documentation repositories generally start with worldwide-telescope-. The Documentation Hub attempts to provide an exhaustive list of documents, with links to source repositories found in each document’s navigation links.

At present, the Git repositories for WWT guides and manuals are essentially simple static HTML websites generated from Markdown files. In particular, they’re generated using a tool called Zola, which is easy to install, self-contained, and very fast. Since the bulk of the content is in standard Markdown, conversion to other formats should be straightforward if needed.

Certain other WWT websites that aren’t quite “documentation”, such as the Documentation Hub index page, are also generated using Zola.

docs.worldwidetelescope.org🔗

Most WWT documentation is served off of the docs.worldwidetelescope.org domain. This domain is essentially a purely static website — the domain is a CDN endpoint that serves content off of _docs subdirectory of the wwtwebstatic Azure Storage account associated with the WWT Azure subscription. Content is updated on this storage account using the CI/CD process described below.

WWT Guide Zola Theme🔗

Most WWT documentation uses the same Zola theme to provide a consistent look and feel. The theme is version-controlled in the zola-wwtguide repository.

For each individual guide, the theme is imported as a Git submodule at the path themes/wwtguide, which means that all of the usual pitfalls from Git submodules come into play. In particular, each guide repository specifies the exact commit from the theme repository that it references. So, if an important change is made to the theme that should be applied globally, you need to go to each and every guide repository and update it to point to the latest version of the theme repository. This is a bit of a hassle, but the flip side is enhanced reproducibility and reliability, and we don’t expect the theme to undergo major upgrades very often.

Deployment Process🔗

Deployment of WWT guides and manuals follows the general scheme seen elsewhere in the project. Merges to the master branch of most documentation repositories trigger a CI/CD pipeline that runs Zola and uploads the generated files to a WWT Azure Storage account that then serves the files as a static website. For most guides this is the wwtwebstatic account backing docs.worldwidetelescope.org as described above.

The details of the CI/CD pipeline for guides are also tracked in the zola-wwtguide repository, in the file azure-build-and-publish.yml. The Azure Pipelines configurations for the indiviual guide repositories pretty much just provide configuration that is fed into this template. Unlike the way that each repository tracks the theme, the way that Azure Pipelines supports this functionality means that every build automatically uses the version of this template on the master branch of the zola-wwtguide repository on GitHub — the specific commit referenced in the themes/wwtguide submodule does not come into play.