Skip to content

Maintaining the documentation#

The narrative documentation is written in markdown and built into HTML using MkDocs, particularly the MkDocs material theme. The source code documentation is generated using Doxygen and adapted for MkDocs using MkDoxy (a tweaked custom fork of the original). The source code of this documentation can be found here.

Tip

In order to edit a page from the documentation, click the button in the top right corner of the page. Please note that this button won't work within the API section of the documentation - the button is removed from there during post-processing, but it will still be visible when serving the website locally.

Serving locally#

To serve the documentation locally, run the make serve target in the docs/dev directory. The server is available at the port designated in the output of the command.

Notes and conventions#

  • When you add new files or rename existing files or section names, be sure to edit the nav property of mkdocs.yml.
  • Always insert links as reference style links. This will make the docs source code more readable and make broken links more easily detectable and replaceable.

Post-processing#

There are some tweaks we make to the generated HTML documentation. We do that in the make build target, by running the post-process.sh script. To see what post-processing we do, see that file.

For this reason, the version of the documentation served locally using make serve will not match the generated HTML documentation 100%. But those inconsistencies are few and minor.

Dependencies#

pip install \
    mkdocs \
    mkdocs-material \
    git+https://github.com/veracioux/mkdoxy@v1.0.0

Note

We use a forked version of mkdoxy that can be found here, that fixes some annoying things from the original.

Deployment#

The developer documentation is served from the official Flameshot website flameshot.org. Here's how.

The official website itself is served from this repo. That repo contains the user documentation. It's deployed using GitHub pages -- the served files can be found on the gh-pages branch of that repo. This branch is automatically created by the build workflow on master.

To make the developer docs available on the official site, we use a custom GitHub action called deploy-dev-docs in the flameshot repo. This action will build and deploy this documentation into the docs/dev subdirectory of the gh-pages branch.

The deploy-dev-docs GitHub workflow#

This workflow checks out the flameshot website repo and does the following:

  • Creates a clean dev-docs-staging branch (we'll explain why, below).
  • Generates the developer docs under docs/dev there and makes a commit
  • Checks out the gh-pages branch and makes the same commit there
  • Force-pushes the dev-docs-staging branch to the website repo
  • Pushes the gh-pages branch to the website repo

Since the gh-pages branch is re-created from scratch by the website deployment workflow, the commit that added the developer documentation will be lost. That's why we have to re-apply the commit during the website deployment workflow as well. That is the reason why we created the dev-docs-staging branch in the first place.

Note

The deploy-dev-docs workflow is set to run on the docs branch as well as master. This branch is used for debugging the developer docs and its associated workflows, without polluting the master branch with unnecessary commits.

Access tokens#

In order to make changes to the website repo from within a workflow in the flameshot repo, the workflow needs to use an access token, which it obtains from the TOKEN_PUSH_TO_WEBSITE_REPO secret.

The following process was used to set it up:

  1. A flameshot organization member with write access must create a personal access token (PAT) here with write access to the website repo.
  2. A secret named TOKEN_PUSH_TO_WEBSITE_REPO must be added to the flameshot repo and its value must be set to the PAT. This can be done here.

For best security practice, the token should be set to expire after some time (currently ~6 months). The token can be regenerated without the need to recreate it. After regeneration you will need to update the TOKEN_PUSH_TO_WEBSITE_REPO secret, which can be done here.

Tip

The currently active PAT is owned by veracioux and is set to expire on July 31 2024. If you notice the token has expired, ask him to re-generate it.