From 6bc123503e934cd7121878fd982fee057f31cd54 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alexis=20M=C3=A9taireau?= Date: Tue, 25 Mar 2025 16:11:21 +0100 Subject: [PATCH] Update docs to use sphinx syntax when possible --- docs/developer/build.md | 76 ++++++++++++++----------------- docs/developer/gvisor.md | 12 +++-- docs/developer/reproducibility.md | 2 +- docs/release/index.md | 38 ++++++++-------- docs/security.md | 1 + 5 files changed, 64 insertions(+), 65 deletions(-) diff --git a/docs/developer/build.md b/docs/developer/build.md index 226c720..9d086c5 100644 --- a/docs/developer/build.md +++ b/docs/developer/build.md @@ -4,34 +4,25 @@ Install dependencies: - - - - -
-
- :memo: Expand this section if you are on Ubuntu 22.04 (Jammy). -
+:::{admonition} Read this section if you are on Ubuntu 22.04 (Jammy). +:collapsible: closed +The `conmon` version that Podman uses and Ubuntu Jammy ships, has a bug +that gets triggered by Dangerzone +(more details in https://github.com/freedomofpress/dangerzone/issues/685). +If you want to run Dangerzone from source, you are advised to install a +patched `conmon` version. A simple way to do so is to enable our +apt-tools-prod repo, just for the `conmon` package: - The `conmon` version that Podman uses and Ubuntu Jammy ships, has a bug - that gets triggered by Dangerzone - (more details in https://github.com/freedomofpress/dangerzone/issues/685). - If you want to run Dangerzone from source, you are advised to install a - patched `conmon` version. A simple way to do so is to enable our - apt-tools-prod repo, just for the `conmon` package: +```bash +sudo cp ./dev_scripts/apt-tools-prod.sources /etc/apt/sources.list.d/ +sudo cp ./dev_scripts/apt-tools-prod.pref /etc/apt/preferences.d/ +``` - ```bash - sudo cp ./dev_scripts/apt-tools-prod.sources /etc/apt/sources.list.d/ - sudo cp ./dev_scripts/apt-tools-prod.pref /etc/apt/preferences.d/ - ``` - - The `conmon` package provided in the above repo was built with the - following [instructions](https://github.com/freedomofpress/maint-dangerzone-conmon/tree/ubuntu/jammy/fpf). - Alternatively, you can install a `conmon` version higher than `v2.0.25` from - any repo you prefer. - -
-
+The `conmon` package provided in the above repo was built with the +following [instructions](https://github.com/freedomofpress/maint-dangerzone-conmon/tree/ubuntu/jammy/fpf). +Alternatively, you can install a `conmon` version higher than `v2.0.25` from +any repo you prefer. +::: ```sh @@ -156,9 +147,9 @@ poetry shell ./dev_scripts/dangerzone ``` -> [!NOTE] -> Prefer running the following command in a Fedora development environment, -> created by `./dev_script/env.py`. +:::{note} +Prefer running the following command in a Fedora development environment, created by `./dev_script/env.py`. You can read more about how to do that [here](./environments). +::: Create a .rpm: @@ -169,11 +160,12 @@ Create a .rpm: ## Qubes OS -> :warning: Native Qubes support is in beta stage, so the instructions below -> require switching between qubes, and are subject to change. -> -> If you want to build Dangerzone on Qubes and use containers instead of disposable -> qubes, please follow the instructions of Fedora / Debian instead. +:::{warning} +Native Qubes support is in beta stage, so the instructions below require +switching between qubes, and are subject to change. If you want to build +Dangerzone on Qubes and use containers instead of disposable qubes, please +follow the instructions of Fedora / Debian instead. +::: ### Initial Setup @@ -293,9 +285,11 @@ QUBES_CONVERSION=1 poetry run ./dev_scripts/dangerzone And when creating a `.rpm` you'll need to enable the `--qubes` flag. -> [!NOTE] -> Prefer running the following command in a Fedora development environment, -> created by `./dev_script/env.py`. +:::{note} +Prefer running the following command in a Fedora development environment, +created by `./dev_script/env.py`. +You can read more about how to do that [here](./environments). +::: ```sh ./install/linux/build-rpm.py --qubes @@ -442,10 +436,10 @@ Install the WiX UI extension. You may need to open a new terminal in order to us wix extension add --global WixToolset.UI.wixext/5.0.2 ``` -> [!IMPORTANT] -> To avoid compatibility issues, ensure the WiX UI extension version matches the version of the WiX Toolset. -> -> Run `wix --version` to check the version of WiX Toolset you have installed and replace `5.x.y` with the full version number without the Git revision. +:::{important} +To avoid compatibility issues, ensure the WiX UI extension version matches the version of the WiX Toolset. +Run `wix --version` to check the version of WiX Toolset you have installed and replace `5.x.y` with the full version number without the Git revision. +::: ### If you want to sign binaries with Authenticode diff --git a/docs/developer/gvisor.md b/docs/developer/gvisor.md index 6898fcd..13d5602 100644 --- a/docs/developer/gvisor.md +++ b/docs/developer/gvisor.md @@ -1,10 +1,5 @@ # gVisor integration -> [!NOTE] -> **Update on 2025-01-13:** There is no longer a copied container image under -> `/home/dangerzone/dangerzone-image/rootfs`. We now reuse the same container -> image both for the inner and outer container. See -> [#1048](https://github.com/freedomofpress/dangerzone/issues/1048). Dangerzone has relied on the container runtime available in each supported operating system (Docker Desktop on Windows / macOS, Podman on Linux) to isolate @@ -27,6 +22,13 @@ as **untrusted**, and the computation and output of the second container as trusted. For this reason, and because we are about to remove the need for the second container, our integration plan will focus on the first container. +:::{versionchanged} 0.9.0 +There is no longer a copied container image under +`/home/dangerzone/dangerzone-image/rootfs`. We now reuse the same container +image both for the inner and outer container. See +[#1048](https://github.com/freedomofpress/dangerzone/issues/1048). +::: + ## Design overview Our integration goals are to: diff --git a/docs/developer/reproducibility.md b/docs/developer/reproducibility.md index 934e5a6..8ee28b2 100644 --- a/docs/developer/reproducibility.md +++ b/docs/developer/reproducibility.md @@ -2,7 +2,7 @@ We want to improve the transparency and auditability of our build artifacts, and a way to achieve this is via reproducible builds. For a broader understanding of -what reproducible builds entail, check out https://reproducible-builds.org/. +what reproducible builds entail, check out [reproducible-builds.org](https://reproducible-builds.org) Our build artifacts consist of: * Container images (`amd64` and `arm64` architectures) diff --git a/docs/release/index.md b/docs/release/index.md index fff66e4..574f0d1 100644 --- a/docs/release/index.md +++ b/docs/release/index.md @@ -75,24 +75,25 @@ Once we are confident that the release will be out shortly, and doesn't need any ``` **Note**: release candidates are suffixed by `-rcX`. -> [!IMPORTANT] -> Because we don't have [reproducible builds](https://github.com/freedomofpress/dangerzone/issues/188) -> yet, building the Dangerzone container image in various platforms would lead -> to different container image IDs / hashes, due to different timestamps. To -> avoid this issue, we should build the final container image for x86_64 -> architectures on **one** platform, and then copy it to the rest of the -> platforms, before creating our .deb / .rpm / .msi / app bundles. +:::{important} +Because we don't have [reproducible builds](https://github.com/freedomofpress/dangerzone/issues/188) +yet, building the Dangerzone container image in various platforms would lead +to different container image IDs / hashes, due to different timestamps. To +avoid this issue, we should build the final container image for x86_64 +architectures on **one** platform, and then copy it to the rest of the +platforms, before creating our .deb / .rpm / .msi / app bundles. +::: ### macOS Release -> [!TIP] -> You can automate these steps from your macOS terminal app with: -> -> ``` -> export APPLE_ID= -> make build-macos-intel # for Intel macOS -> make build-macos-arm # for Apple Silicon macOS -> ``` +:::{tip} +You can automate these steps from your macOS terminal app with: +``` +export APPLE_ID= +make build-macos-intel # for Intel macOS +make build-macos-arm # for Apple Silicon macOS +``` +::: The following needs to happen for both Silicon and Intel chipsets. @@ -274,9 +275,10 @@ repo, by sending a PR. Follow the instructions in that repo on how to do so. #### Fedora -> **NOTE**: This procedure will have to be done for every supported Fedora version. -> -> In this section, we'll use Fedora 41 as an example. +:::{note} +This procedure will have to be done for every supported Fedora version. +In this section, we'll use Fedora 41 as an example. +::: Create a Fedora development environment. You can [follow the instructions in our build section](https://github.com/freedomofpress/dangerzone/blob/main/BUILD.md#fedora), diff --git a/docs/security.md b/docs/security.md index 3fdf07b..3943b9d 100644 --- a/docs/security.md +++ b/docs/security.md @@ -3,6 +3,7 @@ Dangerzone being a privacy-focused tool, it is subject to security advisories. To be updated about future ones, you can follow [the news from the project blog](https://dangerzone.rocks/news/). ```{toctree} +:maxdepth: 1 advisories/2024-12-24.md advisories/2023-12-07.md