Repository Structure

The docs.postmarketos.org website consists of multiple lightweight Sphinx projects:

  • Some are in separate git repositories, such as the pmbootstrap docs.

  • Some are located within docs.postmarketos.org.git in the docs directory, such as the page you are reading right now.

The projects are considered lightweight, as relatively few steps and additional files are needed to add a new one. To make this possible, the theme directory that has our customizations for the Furo theme only exists in one place and gets automatically pulled in as dependency when building any of these Sphinx projects.

Separate Git Repositories

Having Sphinx projects in separate repositories allows to make documentation changes together with code changes (e.g. when introducing a new pmbootstrap feature, we can document it at the same time). Furthermore it is possible to build them standalone, and this is done in CI to ensure changes don’t result in warnings or errors when attempting to build the documenation.

Index Page

The index page located at docs/index/index.md is also a separate Sphinx project. It uses the same theme and links to places where postmarketOS documentation can be found. In addition to the Sphinx projects on the same website, notably the postmarketOS wiki is linked on top as this is currently the place where all of the user-facing documentation is located. Therefore it is most relevant to new postmarketOS users.

Why not make one big Sphinx project instead?

  • We prefer to have documentation close to the place where it is most relevant. Then it can be updated at the same time as making code changes too.

  • There is plenty of information in the wiki as well. By having an index page that just links to several other places where documentation can be found, the wiki is less likely to get over looked compared to having a global search and table of contents that allows accessing all documentation except for the wiki.

  • This approach also allows to only build the part of the documentation that one is currently working on instead of always cloning and building all parts. This is much faster.