Use Sphinx to revamp the documentation

Makefile

@@ -66,6 +66,10 @@ build-macos-arm: build-clean
 build-linux: build-clean
 	doit -n 8 fedora_rpm debian_deb
 
+.PHONY: docs
+develop-docs: ## Compile the documentation
+	poetry run sphinx-autobuild docs docs/_build/html
+
 # Makefile self-help borrowed from the securedrop-client project
 # Explaination of the below shell command should it ever break.
 # 1. Set the field separator to ": ##" and any make targets that might appear between : and ##

docs/advisories/2023-12-07.md

@@ -1,4 +1,4 @@
-Security Advisory 2023-12-07
+# Security Advisory 2023-12-07
 
 In Dangerzone, a security vulnerability was detected in the quarantined
 environment where documents are opened. Vulnerabilities like this are expected
@@ -8,7 +8,7 @@ document may be able to breach the security of Dangerzone. We are not aware of
 any container escapes that affect Dangerzone. **To reduce that risk, you are
 strongly advised to update Dangerzone to the latest version**.
 
-# Summary
+## Summary
 
 A security vulnerability in GhostScript (CVE-2023-43115) affects the
 **contained** environment where the document rendering takes place. If one
@@ -18,12 +18,12 @@ Office documents, which means that you cannot avoid a specific extension. Other
 programs that open Office documents, such as LibreOffice, are also affected,
 unless the system has been upgraded in the meantime.
 
-# How does this impact me?
+## How does this impact me?
 
 The expectation is that malicious code will run in a container without Internet
 access, meaning that it won't be able to infect the rest of the system.
 
-# What do I need to do?
+## What do I need to do?
 
 You are **strongly** advised to update your Dangerzone installation to 0.5.1 as
 soon as possible.

docs/advisories/2024-12-24.md

@@ -1,4 +1,4 @@
-Security Advisory 2024-12-24
+# Security Advisory 2024-12-24
 
 In Dangerzone, a security vulnerability was detected in the quarantined
 environment where documents are opened. Vulnerabilities like this are expected
@@ -8,7 +8,7 @@ document may be able to breach the security of Dangerzone. We are not aware of
 any container escapes that affect Dangerzone. **To reduce that risk, you are
 strongly advised to update Dangerzone to the latest version**.
 
-# Summary
+## Summary
 
 A series of vulnerabilities in gst-plugins-base (CVE-2024-47538, CVE-2024-47607
 and CVE-2024-47615) affects the **contained** environment where the document
@@ -20,14 +20,14 @@ look like regular Office documents, which means that you cannot avoid a specific
 extension. Other programs that open Office documents, such as LibreOffice, are
 also affected, unless the system has been upgraded in the meantime.
 
-# How does this impact me?
+## How does this impact me?
 
 The expectation is that malicious code will run in a container without Internet
 access, meaning that it won't be able to infect the rest of the system.
 
 If you are running Dangerzone via the Qubes OS, you are not impacted.
 
-# What do I need to do?
+## What do I need to do?
 
 You are **strongly** advised to update your Dangerzone installation to 0.8.1 as
 soon as possible.

docs/changelog.md

@@ -0,0 +1 @@
+../CHANGELOG.md

docs/conf.py

@@ -0,0 +1,94 @@
+# -*- coding: utf-8 -*-
+#
+# Dangerzone documentation build configuration file.
+
+import sphinx_rtd_theme
+import os
+
+extensions = [
+    "sphinx_rtd_theme",
+    "myst_parser",
+]
+
+myst_enable_extensions = ["colon_fence"]
+html_sidebars = {
+    "**": [
+        "sidebars/localtoc.html",
+        "repository.html",
+    ]
+}
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+source_suffix = {".md": "markdown"}
+master_doc = "index"
+project = "Dangerzone"
+copyright = "2025, Freedom of the Press Foundation"
+author = "Dangerzone Team and Contributors"
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = "en"
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ["_build"]
+
+pygments_style = "sphinx"
+
+
+html_theme = "sphinx_rtd_theme"
+
+html_context = {
+    "display_github": True,
+    "github_user": "freedomofpress",
+    "github_repo": "dangerzone",
+    "github_version": "main",
+    "conf_py_path": "/docs/",
+    "source_suffix": source_suffix,
+}
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+html_logo = "../static/i/favicon.png"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ["_static"]
+html_css_files = [
+    "rtd_dark.css",
+]
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = "Dangerzonedoc"
+
+man_pages = [(master_doc, "dangerzone", "Dangerzone Documentation", [author], 1)]
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (
+        master_doc,
+        "Dangerzone",
+        "Dangerzone Documentation",
+        author,
+        "Dangerzone",
+        "One line description of project.",
+        "Miscellaneous",
+    ),
+]
+
+linkcheck_retries = 3
+linkcheck_workers = 32
+
+linkcheck_ignore = [
+    r"http://127\.0\.0\.1(:\d+)?/?",
+    r"http://localhost(:\d+)?/?",
+]

docs/developer/build.md

@@ -451,7 +451,7 @@ wix extension add --global WixToolset.UI.wixext/5.0.2
 
 You'll need a code signing certificate.
 
-## To make a .exe
+### To make a .exe
 
 Open a command prompt, cd into the dangerzone directory, and run:
 

docs/index.md

@@ -0,0 +1,119 @@
+# Dangerzone
+
+Take potentially dangerous PDFs, office documents, or images and convert them to a safe PDF.
+
+
+| ![Settings](./assets/screenshot1.png) | ![Converting](./assets/screenshot2.png)
+|--|--|
+
+Dangerzone works like this: You give it a document that you don't know if you can trust (for example, an email attachment). Inside of a sandbox, Dangerzone converts the document to a PDF (if it isn't already one), and then converts the PDF into raw pixel data: a huge list of RGB color values for each page. Then, outside of the sandbox, Dangerzone takes this pixel data and converts it back into a PDF.
+
+_Read more about Dangerzone on the [official site](https://dangerzone.rocks/about/)._
+
+```{toctree}
+:caption: Getting started
+:hidden:
+
+install
+changelog
+security
+```
+
+```{toctree}
+:caption: Developper docs
+:hidden:
+
+developer/build
+developer/environments
+developer/testing
+
+```
+
+```{toctree}
+:caption: Design docs
+:hidden:
+developer/gvisor
+developer/reproducibility
+developer/updates
+````
+
+
+```{toctree}
+:caption: Release
+:hidden:
+release/index
+release/qa
+
+```
+
+## Getting started
+
+Follow the instructions for each platform:
+
+* [macOS](install.md#macos)
+* [Windows](https://github.com/freedomofpress/dangerzone/blob/v0.8.1//INSTALL.md#windows)
+* [Ubuntu Linux](https://github.com/freedomofpress/dangerzone/blob/v0.8.1/INSTALL.md#ubuntu-debian)
+* [Debian Linux](https://github.com/freedomofpress/dangerzone/blob/v0.8.1/INSTALL.md#ubuntu-debian)
+* [Fedora Linux](https://github.com/freedomofpress/dangerzone/blob/v0.8.1/INSTALL.md#fedora)
+* [Qubes OS (beta)](https://github.com/freedomofpress/dangerzone/blob/v0.8.0/INSTALL.md#qubes-os)
+* [Tails](https://github.com/freedomofpress/dangerzone/blob/v0.8.1/INSTALL.md#tails)
+
+## Some features
+
+- Sandboxes don't have network access, so if a malicious document can compromise one, it can't phone home
+- Sandboxes use [gVisor](https://gvisor.dev/), an application kernel written in Go, that implements a substantial portion of the Linux system call interface.
+- Dangerzone can optionally OCR the safe PDFs it creates, so it will have a text layer again
+- Dangerzone compresses the safe PDF to reduce file size
+- After converting, Dangerzone lets you open the safe PDF in the PDF viewer of your choice, which allows you to open PDFs and office docs in Dangerzone by default so you never accidentally open a dangerous document
+
+Dangerzone can convert these types of document into safe PDFs:
+
+- PDF (`.pdf`)
+- Microsoft Word (`.docx`, `.doc`)
+- Microsoft Excel (`.xlsx`, `.xls`)
+- Microsoft PowerPoint (`.pptx`, `.ppt`)
+- ODF Text (`.odt`)
+- ODF Spreadsheet (`.ods`)
+- ODF Presentation (`.odp`)
+- ODF Graphics (`.odg`)
+- Hancom HWP (Hangul Word Processor) (`.hwp`, `.hwpx`)
+  * Not supported on
+    [Qubes OS](https://github.com/freedomofpress/dangerzone/issues/494)
+- EPUB (`.epub`)
+- Jpeg (`.jpg`, `.jpeg`)
+- GIF (`.gif`)
+- PNG (`.png`)
+- SVG (`.svg`)
+- other image formats (`.bmp`, `.pnm`, `.pbm`, `.ppm`)
+
+Dangerzone was inspired by [Qubes trusted PDF](https://blog.invisiblethings.org/2013/02/21/converting-untrusted-pdfs-into-trusted.html), but it works in non-Qubes operating systems. It uses containers as sandboxes instead of virtual machines (using Docker for macOS and Windows, and [podman](https://podman.io/) on Linux).
+
+Set up a development environment by following [these instructions](build.md).
+
+
+## License and Copyright
+
+Licensed under the AGPLv3: [https://opensource.org/licenses/agpl-3.0](https://opensource.org/licenses/agpl-3.0)
+
+Copyright (c) 2022-2024 Freedom of the Press Foundation and Dangerzone contributors
+Copyright (c) 2020-2021 First Look Media
+
+## See also
+
+* [GIJN Toolbox: Cutting-Edge — and Free — Online Investigative Tools You Can Try Right Now](https://gijn.org/stories/cutting-edge-free-online-investigative-tools/)
+* [When security matters: working with Qubes OS at the Guardian](https://www.theguardian.com/info/2024/apr/04/when-security-matters-working-with-qubes-os-at-the-guardian)
+
+## FAQ
+
+### Has Dangerzone received a security audit?
+
+Yes, Dangerzone received its [first security audit](https://freedom.press/news/dangerzone-receives-favorable-audit/) by [Include Security](https://includesecurity.com/) in December 2023. The audit was generally favorable, as it didn't identify any high-risk findings, except for 3 low-risk and 7 informational findings.
+
+### I'm experiencing an issue while using Dangerzone.
+
+Dangerzone gets updates to improve its features _and_ to fix problems. So, updating may be the simplest path to resolving the issue which brought you here. Here is how to update:
+
+1. Check which version of Dangerzone you are currently using: run Dangerzone, then look for a series of numbers to the right of the logo within the app. The format of the numbers will look similar to `0.4.1`
+2. Now find the latest available version of Dangerzone: go to the [download page](https://dangerzone.rocks/#downloads). Look for the version number displayed. The number will be using the same format as in Step 1.
+3. Is the version on the Dangerzone download page higher than the version of your installed app? Go ahead and update.
+

docs/install.md

@@ -1,3 +1,5 @@
+# Install Dangerzone
+
 ## MacOS
 
 - Download [Dangerzone 0.8.1 for Mac (Apple Silicon CPU)](https://github.com/freedomofpress/dangerzone/releases/download/v0.8.1/Dangerzone-0.8.1-arm64.dmg)
@@ -238,7 +240,7 @@ for Tails users.
 
 ## Build from source
 
-If you'd like to build from source, follow the [build instructions](BUILD.md).
+If you'd like to build from source, follow the [build instructions](build.md).
 
 ## Verifying PGP signatures
 

docs/security.md

@@ -0,0 +1,10 @@
+# Security advisories
+
+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}
+
+advisories/2024-12-24.md
+advisories/2023-12-07.md
+advisories/2023-10-25.md
+```

pyproject.toml

@@ -58,6 +58,13 @@ strip-ansi = "*"
 pytest-subprocess = "^1.5.2"
 pytest-rerunfailures = "^14.0"
 
+# Dependencies required for the documentation
+[tool.poetry.group.docs.dependencies]
+sphinx = "^7.4"
+sphinx-autobuild = "^2024.10.3"
+sphinx-rtd-theme = "^3.0.2"
+myst-parser = "^3.0.0"
+
 [tool.poetry.group.debian.dependencies]
 pymupdf = "^1.24.11"