Documentation Guidelines¶
SecureDrop’s documentation is available at https://docs.securedrop.org. It is
written in reStructuredText (reST) and hosted by Freedom of the Press Foundation
using a theme by Read the Docs. The documentation files
are stored in the docs/
directory of the SecureDrop docs repository.
Documentation versions¶
Note
SecureDrop maintains two documentation versions: stable
and latest.
stable
is the default, and is built from our latest signed git tag.
latest
is built from the head of the 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 documentation site.
Updating Documentation¶
To get started editing the docs:
Clone the SecureDrop documentation repository:
git clone https://github.com/freedomofpress/securedrop-docs.git
Install the dependencies:
Note
You can install, upgrade, and remove Python packages using
pip
, the Python package installer. By default,pip
will attempt to install packages system-wide. Usevenv
orvirtualenv
to avoid installing Python packages globally and to isolate the installation of dependencies of a specific application.Run the command
python3 -m venv .venv
to create and manage your virtual environment. To begin using the virtual environment, use the commandsource .venv/bin/activate
to activate.You can also use virtualenvwrapper which provides the
mkvirtualenv
shell function and is a set of extensions to thevirtualenv
tool. 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:
make docs
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
main
branch of the SecureDrop docs repository.
Testing Documentation Changes¶
You can check for formatting violations by running the linting option:
make docs-lint
The 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:
make docs-linkcheck
Project maintainers will need to approve the PR before it can be merged.
Note
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.
Pushing to a contributor fork¶
As a maintainer, you can push directly to a contributor fork, as long as there
is an active Pull Request corresponding to the branch you are pushing to, and
you have added the contributor remote with authentication enabled (i.e. the url
value in .git/config
starts with git@github.com
).
Updating Screenshots¶
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.
Prior to generating screenshots as part of a release update:
Ensure that the version string shown in the screenshots is the version that will be released. You can manually edit
securedrop/version.py
in your SecureDrop repository checkout if it currently contains a release candidate string.Configure the New York World sample instance logo. Because the functional tests used to generate the logo may themselves update the logo, it is safest to temporarily overwrite the stock logo in
securedrop/static/i/logo.png
in your SecureDrop repository checkout.
Note
The automated screenshots update does not update screenshots for Tails, the Tor Browser UI, the firewall captive portal, etc. If you notice discrepancies in those screenshots, please open issues so they can be addressed at a later point.
Updating Upgrade Guides¶
We ship an upgrade guide for each release; see the latest guide as an example. As part of updating the documentation for a release:
Create a new upgrade guide copied from the most recent one and add it to the index.
Ensure that the
latest_upgrade_guide
reference at the top of the document is only present in the latest upgrade guide.If this is a major-level or minor-level release, remove the oldest upgrade guide and associated patch-level guides from the documentation.
Example: If you are adding a guide to upgrade from 4.5.0 to 4.6.0, and the oldest guide present is from 4.2.0 to 4.3.0, remove it along with any guides for 4.2.1, 4.2.2, etc.).
If this is a major-level or minor-level release, make sure to include the reminders in
docs/includes/backup-and-update-reminders.txt
towards the end of the document.If this release includes a kernel update, make sure to include a reference to the Kernel Troubleshooting Guide.
If you are not also the release manager, check with them about any other pertinent release-specific instructions that should be included.
Style Guide¶
Please see the reStructuredText Primer by the Sphinx project as a reference for writing in the markup language used for this documentation.
Code Blocks¶
Ensure that example commands in codeblocks are easy to copy and paste.
Do not prepend the $
shell prompt indicator to example commands:
echo hello
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
Date Format¶
Follow AP guidelines for formatting dates. Don’t use the ISO format for adding dates to the documentation.
To avoid confusion, format dates in the documentation as Month_Name Day, Year:
October 13, 2020not
13 October, 2020 13/10/2020 10/13/2020 10/13/20 2020-10-13 2020-Oct-13
File Paths¶
Cloning the SecureDrop git repository creates a directory
called securedrop
. This 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 ./some_dir/file
, where .
is the top level directory
of the SecureDrop repo.
Use absolute paths when refering to files outside the SecureDrop repository:
/usr/local/bin/tor-browser
.
Glossary¶
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:
app-staging VM
Line Wrapping¶
Lines in the plain-text documentation files should wrap at 80 characters. (Some exceptions: complex code blocks showing example commands, or long URLs.)
Usage and Style¶
To avoid confusion, lists should include the “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 ================ Set up the Environment ----------------------not
Before you begin ================ Set up the environment ----------------------