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.
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.
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
navproperty 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.
There are some tweaks we make to the generated HTML documentation. We do that in
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
serve will not match the generated HTML documentation 100%. But those
inconsistencies are few and minor.
pip install \ mkdocs \ mkdocs-material \ git+https://firstname.lastname@example.org
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
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/devthere 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.
The deploy-dev-docs workflow is set to run on the
docs branch as well as
This branch is used for debugging the developer docs and its associated
workflows, without polluting the
master branch with unnecessary commits.
The following process was used to set it up:
- A flameshot organization member with write access must create a personal access token (PAT) here with write access to the website repo.
- A secret named
TOKEN_PUSH_TO_WEBSITE_REPOmust 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
secret, which can be done here.
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.