SecureDrop’s documentation is written in ReStructuredText (ReST),
and is built by and hosted on Read the Docs (RTD). The
documentation files are stored in the primary SecureDrop git
repository under the
To get started editing the docs:
Clone the SecureDrop repository:
git clone https://github.com/freedomofpress/securedrop.git
Install the dependencies:
pip install -r securedrop/requirements/develop-requirements.txt
Build the docs and open the index page in your web browser:
If you have the Development VM running, you should run
make docs from within the
/vagrant directory inside the VM, otherwise
the forwarded port on 8000 will collide with sphinx-autobuild process running
You can then can browse the documentation at http://127.0.0.1:8000/. As you make changes, the docs will automatically rebuild in the browser window, so you don’t need to refresh the page manually.
Testing documentation changes¶
You can check the docs for formatting violations by running the linting option:
make docs command will display warnings, but will still build the
documentation if formatting mistakes are found. Using
will convert any warnings to errors, causing the build to fail.
The CI tests will automatically perform linting via the same
The CI tests by default create staging servers to test the
application code. If your PR only makes documentation changes, you should
prefix the branch name with
docs- to skip the staging run. Project
maintainers will still need to approve the PR prior to merge, and the linting
checks will also still run.
The user guides for SecureDrop contain screenshots of the web applications.
To update these screenshots automatically, from
/vagrant inside a
development VM you can run:
This will generate screenshots for each image in the web application and copy
them to the folder under
docs/images/manual/screenshots 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.
Integration with Read the Docs¶
SecureDrop maintains two branches of documentation, stable
the former being the default used by our Read the Docs powered site.
stable is built from our latest signed git tag, while
is built from the head of the
develop git branch. In almost all
cases involving development work, you’ll want to make sure you have
latest version selected by clicking the appropriate link
above, or by using the menu in the bottom left corner.
When specific elements from a user interface are mentioned by name or by label, bold it.
“Once you’re sure you have the right drive, click Format Drive.”
When SecureDrop-specific terminology is used, italicize it.
“To get started, you’ll need two Tails drives: one for the Admin Workstation and one for the Secure Viewing Station.”
Try to keep your lines wrapped to near 80 characters when editing the docs. Some exceptions are warranted, such as complex code blocks showing example commands, or long URLs, but in general the docs should be tightly wrapped.
When referring to virtual machines in the development environment, use lowercase for the name:
Ensure that example commands in codeblocks are easily copy/pasteable.
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, then use
$, but only on the typed command lines:
$ echo hello hello $ echo sunshine sunshine
Use absolute paths when referring to files outside the SecureDrop repository. Exceptions made for when it’s clear from the surrounding context what the intended working directory is. For files inside the SecureDrop directory, write them as ./some_dir/file, where . is the top level directory of the SecureDrop repo. Since by default the git repo will be cloned under the name securedrop and it also contains a securedrop subdirectory this is intended to avoid confusion. Exceptions made for when it’s clear from the context we’re outside of the SecureDrop repo, but would like to somehow interact with it (e.g., we just cloned the repo and now we’re going to cd into it).