SecureDrop’s documentation is available at https://docs.securedrop.org. It is
written in reStructuredText (reST),
and is built by and hosted on Read the Docs (RTD). The documentation files
are stored in the
docs/ directory of the SecureDrop docs repository.
Integration with Read the Docs¶
SecureDrop maintains two versions of documentation: stable
stable is the default used by our Read the Docs site, and is built
from our latest signed git tag.
latest is built from the head of
main git branch of the securedrop-docs repository.
In almost all cases involving development work, you’ll want to make
sure you have the
latest version selected by using the menu in the
bottom left corner of the Read the Docs site.
To get started editing the docs:
The SecureDrop docs repository stores binaries such as screenshots via Git Large File Storage (LFS). If not already present, install Git LFS by following the install guide.
Clone the SecureDrop documentation repository:
git clone https://github.com/freedomofpress/securedrop-docs.git
Install the dependencies:
You can install, upgrade, and remove Python packages using
pip, the Python package installer. By default,
pipwill attempt to install packages system-wide. Use
virtualenvto avoid installing Python packages globally and to isolate the installation of dependencies of a specific application.
Run the command
python3 -m venv .venvto create and manage your virtual environment. To begin using the virtual environment, use the command
source .venv/bin/activateto activate.
You can also use virtualenvwrapper which provides the
mkvirtualenvshell function and is a set of extensions to the
virtualenvtool. The extensions include wrappers for creating and deleting virtual environments and otherwise managing your development workflow.
pip install --require-hashes -r requirements/requirements.txt
Build the docs for viewing in your web browser:
You can then preview the documentation at http://127.0.0.1:8000. Navigate to the
docs/directory to make changes to the documentation rendered on https://docs.securedrop.org. The documentation pages will automatically rebuild in the browser window, as you make changes; you don’t need to refresh the page manually.
After performing lint checks, open a PR against the
mainbranch of the SecureDrop docs repository.
Testing Documentation Changes¶
You can check for formatting violations by running the linting option:
make docs command will display warnings if mistakes are found, but will
still build the documentation. Using
make docs-lint will convert any warnings
to errors, causing the build to fail.
To test the documentation for broken links, run the following command from a reliable internet connection:
Project maintainers will need to approve the PR before it can be merged.
It is generally good practice to maintain a clean git history by reducing the number of commits to a reasonable minimum. You can do this by squashing closely related commits through an interactive rebase once your PR is close to being merged. If you are unfamiliar with how to squash commits with rebase, check out this blog post.
If you would like a project maintainer to help you with squashing commits in a PR, please don’t hesitate to leave a comment requesting assistance.
The user guides for SecureDrop contain screenshots of the web applications. To update these screenshots automatically you can run this command from within your main SecureDrop repository checkout:
DOCS_REPO_DIR=/path/to/docs make update-user-guides
This will generate screenshots for each page in the web application and copy
them to the folder
docs/images/manual/screenshots in your documentation
repository checkout, where they will replace the existing screenshots. Stage for
commit any screenshots you wish to update. If you wish to update all screenshots,
simply stage for commit all changed files in that directory.
Please see the reStructuredText Primer by the Sphinx project as a reference for writing in the markup language used for this documentation.
Lines in the plain-text documentation files should wrap at 80 characters. (Some exceptions: complex code blocks showing example commands, or long URLs.)
Text taken directly from a user interface is in bold face.
“Once you’re sure you have the right drive, click Format Drive.”
SecureDrop-specific glossary is in italics.
“To get started, you’ll need two Tails drives: one for the Admin Workstation and one for the Secure Viewing Station.”
When referring to virtual machines in the development environment, use lowercase for the name:
Ensure that example commands in codeblocks are easy to copy and paste.
Do not prepend the
$ shell prompt indicator to example commands:
In the context of a terminal session with both typed commands and printed
output text, use
$ before the typed commands:
$ echo hello hello $ echo sunshine sunshine
Cloning the SecureDrop git repository creates a directory
securedrop directory also contains a
securedrop subdirectory for app code.
. ├── securedrop │ │ │ ... │ ├── securedrop ... ...
To avoid confusion, paths to files anywhere inside the SecureDrop git repository
should be written as
. is the top level directory
of the SecureDrop repo.
Use absolute paths when refering to files outside the SecureDrop repository:
Usage and Style¶
To avoid confusion, lists should include the so-called “Oxford comma”:
“You will need an email address, a public GPG key for that address, and the fingerprint for that key.”
Capitalize all section headings in title case:
Before You Begin ================ Read the Docs -------------
notBefore you begin ================ Read the docs -------------