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:
- publication: JSEA Paper
- talks: GRDevDay, BarCamp
- sample: Generated HTML
- documentation: API, Demo
- 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 https://github.com/jacebrowning/doorstop.git
$ cd doorstop
$ python setup.py 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__
Parent Document
After configuring version control, a new parent document can be created:
$ doorstop new REQ ./reqs
created document: REQ (@/reqs)
Items can be added to the document and edited:
$ doorstop add REQ
added item: REQ001 (@/reqs/REQ001.yml)
$ doorstop edit REQ1
opened item: REQ001 (@/reqs/REQ001.yml)
Child Documents
Additional documents can be created that link to other documents:
$ doorstop create TST ./reqs/tests --parent REQ
created document: TST (@/reqs/tests)
Items can be added and linked to parent items:
$ doorstop add TST
added item: TST001 (@/reqs/tests/TST001.yml)
$ doorstop link TST1 REQ1
linked item: TST001 (@/reqs/tests/TST001.yml) -> REQ001 (@/reqs/REQ001.yml)
To check a document hierarchy for consistency, run the main command:
$ doorstop
valid tree: REQ <- [ TST ]
A text report of a document can be displayed:
$ doorstop publish TST
1 TST001
Verify the foobar will foo and bar.
Links: REQ001
Other formats are also supported:
$ doorstop publish TST --html
<!DOCTYPE html>
...
<body>
<h1>1 (TST001)</h1>
<p>Verify the foobar will foo and bar.</p>
<p><em>Links: REQ001</em></p>
</body>
</html>
Or a file can be created using one of the supported extensions:
$ doorstop publish TST path/to/tst.md
publishing TST to path/to/tst.md...
Supported formats:
- Text: .txt
- Markdown: .md
- HTML: .html
Export
Documents can be exported for editing or to exchange with other systems:
$ doorstop export TST
TST001:
active: true
dervied: false
level: 1
links:
- REQ001
normative: true
ref: ''
text: |
Verify the foobar will foo and bar.
Or a file can be created using one of the supported extensions:
$ doorstop export TST path/to/tst.csv
exporting TST to path/to/tst.csv...
exported: path/to/tst.csv
Supported formats:
- YAML: .yml
- Comma-Separated Values: .csv
- Tab-Separated Values: .tsv
- Microsoft Office Excel: .xlsx
Import
Items can be created/updated from the export formats:
$ doorstop import path/to/tst.csv TST
- GNU Make:
- Windows: http://cygwin.com/install.html
- Mac: https://developer.apple.com/xcode
- Linux: http://www.gnu.org/software/make (likely already installed)
- virtualenv: https://pypi.python.org/pypi/virtualenv#installation
- Pandoc: http://johnmacfarlane.net/pandoc/installing.html
- Graphviz: http://www.graphviz.org/Download.php
Create a virtualenv:
make env
Run the tests:
make test
make tests # includes integration tests
Build the documentation:
make doc
Run static analysis:
make pep8
make pep257
make pylint
make check # includes all checks
Prepare a release:
make dist # dry run
make upload