Add developer docs (flameshot-org#3097)

* Create developer docs

* Remove mike dependency

* Update docs

* Make docs/dev self-contained

* Add incomplete deploy-dev-docs workflow

* Fix typo

* Add workflow file to path:

* Add doxygen as dependency

* Add remaining deploy steps

* Add working-directory

* Fix working-directory error

* Add missing Makefile

* Change flameshot website repo url

* Change working-directory for safety step

* Add git credentials

* Change push credentials

* Use different token secret

* Remove checkpoints

* Add separate branch developer-docs

* Add || true

* Update docs

* Update the 'Maintaining the documentation' docs

* Fix error in deploy-dev-docs workflow

* Remove accidentally committed file DOC.md

* Update PAT expiry date

* Rename developer-docs branch to dev-docs-staging

(cherry picked from commit a2f036b)

.github/workflows/deploy-dev-docs.yml

@@ -0,0 +1,75 @@
+name: Deploy developer docs
+
+on:
+  push:
+    branches: [ master, docs ]
+    paths:
+      - 'src/**'
+      - 'docs/dev/**'
+      - '.github/workflows/deploy-dev-docs.yml'
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Install dependencies
+        run: |
+          sudo apt-get --yes --quiet update
+          sudo apt-get --yes --no-install-recommends install doxygen
+          pip install \
+              mkdocs \
+              mkdocs-material \
+              git+https://github.com/veracioux/mkdoxy@v1.0.0
+
+      - name: Checkout flameshot source
+        uses: actions/checkout@v3
+        with:
+          path: 'flameshot'
+
+      - name: Build docs
+        working-directory: ${{github.workspace}}/flameshot/docs/dev
+        run: |
+          make build
+
+      - name: Checkout flameshot website
+        uses: actions/checkout@v3
+        with:
+          repository: 'flameshot-org/flameshot-org.github.io'
+          ref: 'gh-pages'
+          path: 'website'
+
+      - name: Configure git credentials for website repo
+        working-directory: ${{github.workspace}}/website
+        run: |
+          git config user.name "GitHub Actions"
+          git config user.email "github-actions-bot@users.noreply.github.com"
+          git config http.https://github.com/.extraheader 'AUTHORIZATION basic ${{secrets.TOKEN_PUSH_TO_WEBSITE_REPO}}'
+          git remote add destination "https://x-access-token:${{secrets.TOKEN_PUSH_TO_WEBSITE_REPO}}@github.com/flameshot-org/flameshot-org.github.io"
+
+      - name: Add developer docs to website deployment
+        working-directory: ${{github.workspace}}/website
+        run: |
+          # Create empty dev-docs-staging branch
+          git checkout --orphan dev-docs-staging
+          git rm -r --cached .
+          rm -rf docs/dev
+          # Copy generated docs over
+          mkdir -p docs
+          mv "${{github.workspace}}/flameshot/docs/dev/output" \
+             "./docs/dev"
+          # Commit docs/dev to the dev-docs-staging branch
+          git add docs/dev
+          HASH="$(git --git-dir="${{github.workspace}}/flameshot/.git" rev-parse HEAD)"
+          git commit --message "Add developer docs from flameshot@$HASH"
+          # Apply changes to gh-pages
+          git checkout --force gh-pages
+          git checkout dev-docs-staging -- docs/dev
+          # Commit (we use `|| true` because the commit could be empty and thus fail)
+          git commit --message "Add developer docs from flameshot@$HASH" || true
+
+      - name: Push to website repo
+        working-directory: ${{github.workspace}}/website
+        run: |
+          git push --force destination dev-docs-staging
+          git push destination gh-pages
+

.gitignore

@@ -72,3 +72,6 @@ data/flatpak/.flatpak-builder
 
 #MacOS Crap
 .DS_Store
+
+# Miscellaneous
+!docs/dev/Makefile

docs/dev/.gitignore

@@ -0,0 +1,2 @@
+output
+mkdoxy-generated

docs/dev/Makefile

@@ -0,0 +1,9 @@
+serve:
+	mkdocs serve --dev-addr localhost:8080 --watch ../../src
+build:
+	mkdocs build
+	@echo "Post-processing..."
+	@bash post-process.sh
+	@echo "DONE."
+clean:
+	rm -rf mkdoxy-generated output

docs/dev/mkdocs.yml

@@ -0,0 +1,47 @@
+site_name: Flameshot Developer Docs
+site_url: https://flameshot.org/docs/dev/
+repo_url: https://github.com/flameshot-org/flameshot/
+edit_uri: tree/master/docs/dev/src
+docs_dir: src
+site_dir: output
+markdown_extensions:
+  - admonition
+  - attr_list
+  - toc:
+      permalink: "#"
+  - pymdownx.emoji:
+      emoji_index: !!python/name:materialx.emoji.twemoji
+      emoji_generator: !!python/name:materialx.emoji.to_svg
+
+plugins:
+  - search
+  - mkdoxy:
+      projects:
+        flameshot:
+          src-dirs: ../../src/
+          full-doc: True
+          doxy-cfg:
+            FILE_PATTERNS: "*.cpp *.h"
+            # #TODO for some reason this causes an exception
+            EXCLUDE_PATTERNS: "*/capturetool.h"
+            FULL_PATH_NAMES: "NO"
+            SHOW_USED_FILES: "NO"
+            RECURSIVE: True
+
+      save-api: mkdoxy-generated
+      debug: True
+      ignore-errors: False
+
+theme:
+  name: material
+  logo: https://flameshot.org/flameshot-icon.svg
+
+nav:
+  - Overview: index.md
+  - Debugging: debugging.md
+  - FAQ: faq.md
+  - 'Maintaining the documentation': docs.md
+  - API:
+      - Classes: flameshot/classes.md
+      - 'Class Hierarchy': flameshot/hierarchy.md
+      - Files: flameshot/files.md

docs/dev/post-process.sh

@@ -0,0 +1,19 @@
+# Only run this script from the Makefile
+
+shopt -s globstar
+cd output
+
+# Classes backlink to the ClassList in their breadcrumbs. We use the ClassIndex
+# instead.
+rm -rf flameshot/annotated
+ln -sf classes flameshot/annotated
+
+# Hide 'Edit this page button' from the auto-generated docs pages
+# It would be better to change the button to link to the file on github, but
+# it seems like too much work right now.
+sed -i 's|title="Edit this page"|& style="display: none !important"|' flameshot/*/*.html
+
+# MkDoxy adds Qt classes into the class hierarchy. We don't want that.
+sed -i 's|<li><strong>class</strong> <strong>Q[^<]*</strong>  </li>||' flameshot/*/*.html
+
+# vim: filetype=bash

docs/dev/src/debugging.md

@@ -0,0 +1,16 @@
+# Debugging
+
+## `FLAMESHOT_DEBUG_CAPTURE`
+
+With this cmake variable set to `ON`, the flameshot capture GUI window won't bypass the
+window manager. This allows you to manipulate the capture GUI window like any
+other window while debugging.
+
+This can be useful if a debugging breakpoint is triggered while flameshot is in
+full screen mode. Without this variable, you might have trouble inspecting the
+code due to a frozen full-screen window.
+
+Usage:
+```shell
+cmake -DFLAMESHOT_DEBUG_CAPTURE=ON ...
+```

docs/dev/src/docs.md

@@ -0,0 +1,141 @@
+# Maintaining the documentation
+
+The narrative documentation is written in markdown and built into HTML using
+[MkDocs][mkdocs], particularly the [MkDocs material theme][mkdocs-material]. The
+source code documentation is generated using Doxygen and adapted for MkDocs
+using [MkDoxy][mkdoxy] (a tweaked custom fork of the original). The source code
+of this documentation can be found [here][doc-source].
+
+!!! tip
+
+    In order to edit a page from the documentation, click the :material-pencil:
+    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].
+
+## 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][mkdocs.yml].
+- Always insert links as [reference style
+  links][markdown: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][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
+```shell
+pip install \
+    mkdocs \
+    mkdocs-material \
+    git+https://github.com/veracioux/mkdoxy@v1.0.0
+```
+
+!!! note
+
+    We use a forked version of [mkdoxy][mkdoxy-original] that can be found
+    [here][mkdoxy], that fixes some annoying things from the original.
+
+## Deployment
+
+The developer documentation is served from the official Flameshot website
+[flameshot.org][website]. Here's how.
+
+The official website itself is served from this [repo][website-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][website-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][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][website-build], 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][website-build] as well. **That is the reason why
+we created the** [**dev-docs-staging**][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][website-repo] from within a
+workflow in the [flameshot repo][flameshot], 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][PAT] with write access to the [website repo][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][action-secrets].
+
+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][edit-secret].
+
+!!! 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.
+
+<!-- Internal links -->
+[post-processing]: #post-processing
+[serving-locally]: #serving-locally
+
+<!-- Flameshot-related pages -->
+[flameshot]: https://github.com/flameshot-org/flameshot
+[website]: https://flameshot.org
+[doc-source]: https://github.com/flameshot-org/flameshot/tree/master/docs/dev
+[website-repo]: https://github.com/flameshot-org/flameshot-org.github.io
+[gh-pages]: https://github.com/flameshot-org/flameshot-org.github.io/tree/gh-pages
+[dev-docs-staging]: https://github.com/flameshot-org/flameshot-org.github.io/tree/dev-docs-staging
+[action-secrets]: https://github.com/flameshot-org/flameshot/settings/secrets/actions
+[edit-secret]: https://github.com/flameshot-org/flameshot/settings/secrets/actions/TOKEN_PUSH_TO_WEBSITE_REPO
+
+<!-- Files in flameshot repo -->
+[mkdocs.yml]: https://github.com/flameshot-org/flameshot/blob/master/docs/dev/mkdocs.yml
+[post-process.sh]: https://github.com/flameshot-org/flameshot/blob/master/docs/dev/post-process.sh
+[deploy-dev-docs]: https://github.com/flameshot-org/flameshot/blob/master/.github/workflows/deploy-dev-docs.yml
+
+<!-- Files in flameshot website repo -->
+[website-build]: https://github.com/flameshot-org/flameshot-org.github.io/blob/master/.github/workflows/build.yml
+
+<!-- External pages -->
+[markdown:reference-style-links]: https://www.markdownguide.org/basic-syntax/#reference-style-links
+[mkdocs]: https://www.mkdocs.org/
+[mkdocs-material]: https://squidfunk.github.io/mkdocs-material
+[mkdoxy-original]: https://github.com/JakubAndrysek/mkdoxy
+[mkdoxy]: https://github.com/veracioux/mkdoxy
+[PAT]: https://github.com/settings/tokens?type=beta
+[veracioux]: https://github.com/veracioux

docs/dev/src/faq.md

@@ -0,0 +1,47 @@
+
+# FAQ
+
+!!! todo
+
+    Incomplete page.
+
+### How do I create a new subcommand?
+
+### How do I add a new tool?
+
+### How do I add a new config setting?
+
+There are currently two groups of settings: `General` and `Shortcuts`.
+The necessary steps are usually the following:
+
+- Determine a name for the setting - for a general setting, it must be a valid
+  C++ identifier, for a shortcut it must be the name of a tool type from TODO.
+- Add a getter and a setter for the setting in [`ConfigHandler`][ConfigHandler].
+  For most settings you should use the
+  [`CONFIG_GETTER_SETTER`][CONFIG_GETTER_SETTER] macro. If your setting is
+  unusual enough you may need to use [`CONFIG_GETTER`][CONFIG_GETTER] or
+  [`CONFIG_SETTER`][CONFIG_SETTER] individually, or even need to create the
+  methods manually.
+- If you need custom validation or conversion for the value, you must create a
+  subclass of [`ValueHandler`][ValueHandler]. Otherwise you can use one of the
+  existing ones in [valuehandler.h][].
+- If you want to make your setting available in the configuration GUI (usually
+  you do), you should add the appropriate widgets into one of the tabs of
+  [`ConfigWindow`][ConfigWindow]. If your setting doesn't fit into any of the
+  existing tabs, you can add a new one, but please discuss it with us first.
+
+To get a deeper understanding of how the configuration works, please see
+[Configuration][config].
+
+### How do I add a new export action? (@borgmanJeremy @mehrad This is my preferred terminology over final action, need consensus)
+
+[config]: index.md#configuration
+[confighandler.h]: flameshot/confighandler_8h
+[confighandler.cpp]: flameshot/confighandler_8cpp
+[valuehandler.h]: flameshot/valuehandler_8h
+[ValueHandler]: flameshot/classValueHandler
+[ConfigHandler]: flameshot/classConfigHandler
+[ConfigWindow]: flameshot/classConfigWindow
+[CONFIG_GETTER_SETTER]: flameshot/confighandler_8h/#define-config_getter_setter
+[CONFIG_GETTER]: flameshot/confighandler_8h/#define-config_getter
+[CONFIG_SETTER]: flameshot/confighandler_8h/#define-config_setter