Documentation Guidelines

Caution

This is an early draft. Our documentation guidelines are subject to change at any time until this notice is removed.

Warning

We recently auto-converted the documentation from Markdown to ReST, and are still cleaning up the output from that auto-conversion. If you find style issues, broken links or references, or any other similar issues, pull requests are welcome!

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 docs/ directory.

To get started editing the docs:

  1. Install the dependencies:

    $ pip install sphinx sphinx-autobuild sphinx_rtd_theme
    
  2. Clone the SecureDrop repository:

    $ git clone https://github.com/freedomofpress/securedrop.git
    $ cd securedrop/docs
    
  3. Build the docs and open the index page in your web browser:

    $ make html
    $ open _build/html/index.html
    

    Tip

    You can use sphinx-autobuild to automatically rebuild and reload your docs as you work on them. Run sphinx-autobuild . _build/html.

Occasionally, the docs get out of whack and rebuilding them doesn’t work as it should. You can usually resolve this by clearing out the build artifacts and re-building the docs from scratch:

$ make clean && make html

Integration with Read the Docs

Our documentation is built and hosted by Read the Docs and is available at https://securedrop.readthedocs.org. The “latest” documentation is currently based on the develop branch of the upstream Git repository. We use a webhook so the docs are rebuilt automatically when commits get pushed to the branch.

Style Guide

  • 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.”