STATUS: As of the 1.0 release, this project is no longer under active development. I still plan on accepting any passing pull requests to become part of future 2.x releases.


Build Status Coverage Status Scrutinizer Code Quality PyPI Version PyPI Downloads

Doorstop manages the storage of textual requirements alongside source code in version control.

When a project utilizes this tool, each linkable item (requirement, test case, etc.) is stored as a YAML file in a designated directory. The items in each directory form a document. The relationship between documents forms a tree hierarchy. Doorstop provides mechanisms for modifying this tree, validating item traceability, and publishing documents in several formats.

Additional reading:

Getting Started


  • Python 3.3+
  • A version control system for requirements storage


Doorstop can be installed with pip:

$ pip install doorstop

or directly from source:

$ git clone
$ cd doorstop
$ python install

After installation, Doorstop is available on the command-line:

$ doorstop --help

And the package is available under the name 'doorstop':

$ python
>>> import doorstop
>>> doorstop.__version__

Basic Usage

Switch to an existing version control working directory, or create one:

$ git init .

Create a document

Create a new parent requirements document:

$ doorstop create SRD ./reqs/srd

Add a few items to that document:

$ doorstop add SRD
$ doorstop add SRD
$ doorstop add SRD

Create a child document to link to the parent:

$ doorstop create HLTC ./tests/hl --parent SRD
$ doorstop add HLTC

Link items between documents:

$ doorstop link HLTC001 SRD002

Publish reports

Run integrity checks on the document tree:

$ doorstop

Publish the documents as HTML:

$ doorstop publish all ./public