+
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.
+Doorstop is under active development and we welcome contributions.
+
+The project is licensed as GPLv3.
+
+To report a problem or a security vulnerability please raise an [issue](https://github.com/jacebrowning/doorstop/issues)
+
Additional reading:
- publication: [JSEA Paper](http://www.scirp.org/journal/PaperInformation.aspx?PaperID=44268#.UzYtfWRdXEZ)
- talks: [GRDevDay](https://speakerdeck.com/jacebrowning/doorstop-requirements-management-using-python-and-version-control), [BarCamp](https://speakerdeck.com/jacebrowning/strip-searched-a-rough-introduction-to-requirements-management)
- sample: [Generated HTML](http://jacebrowning.github.io/doorstop/index.html)
+
# Setup
## Requirements
@@ -33,13 +35,13 @@ Additional reading:
Install Doorstop with pip:
-```
+```sh
$ pip install doorstop
```
or directly from source:
-```
+```sh
$ git clone https://github.com/jacebrowning/doorstop.git
$ cd doorstop
$ python setup.py install
@@ -47,13 +49,13 @@ $ python setup.py install
After installation, Doorstop is available on the command-line:
-```
+```sh
$ doorstop --help
```
And the package is available under the name 'doorstop':
-```
+```sh
$ python
>>> import doorstop
>>> doorstop.__version__
@@ -63,7 +65,7 @@ $ python
Switch to an existing version control working directory, or create one:
-```
+```sh
$ git init .
```
@@ -71,13 +73,13 @@ $ git init .
Create a new parent requirements document:
-```
+```sh
$ doorstop create SRD ./reqs/srd
```
Add a few items to that document:
-```
+```sh
$ doorstop add SRD
$ doorstop add SRD
$ doorstop add SRD
@@ -87,14 +89,14 @@ $ doorstop add SRD
Create a child document to link to the parent:
-```
+```sh
$ doorstop create HLTC ./tests/hl --parent SRD
$ doorstop add HLTC
```
Link items between documents:
-```
+```sh
$ doorstop link HLTC001 SRD002
```
@@ -102,12 +104,12 @@ $ doorstop link HLTC001 SRD002
Run integrity checks on the document tree:
-```
+```sh
$ doorstop
```
Publish the documents as HTML:
-```
+```sh
$ doorstop publish all ./public
```
diff --git a/app.json b/app.json
new file mode 100644
index 000000000..acb9882cb
--- /dev/null
+++ b/app.json
@@ -0,0 +1,7 @@
+{
+ "buildpacks": [
+ {
+ "url": "heroku/python"
+ }
+ ]
+}
diff --git a/bin/example-adapter.wsgi b/bin/example-adapter.wsgi
new file mode 100644
index 000000000..5a9cf01dc
--- /dev/null
+++ b/bin/example-adapter.wsgi
@@ -0,0 +1,34 @@
+#!/usr/bin/env python3
+#
+# Example adapter.wsgi for doorstop.
+
+import os
+import sys
+import bottle
+
+app = None
+
+def application(environ, start_response):
+ global app
+ if not app:
+ doorstop_path = "/opt/doorstop"
+ os.chdir(os.path.dirname(__file__))
+
+ project_path = environ['DOORSTOP_PROJECT_DIR']
+ baseurl = environ['DOORSTOP_BASE_URL']
+
+ parameters = [
+ '--project', project_path,
+ '--baseurl', baseurl
+ '--wsgi'
+ ]
+
+ sys.path.append(doorstop_path)
+ from doorstop.server.main import main as servermain
+
+ servermain(parameters)
+
+ app = bottle.default_app()
+
+ return app(environ, start_response)
+
diff --git a/bin/post_compile b/bin/post_compile
new file mode 100755
index 000000000..6b2bb6c39
--- /dev/null
+++ b/bin/post_compile
@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+
+set -eo pipefail
+
+indent() {
+ sed "s/^/ /"
+}
+
+puts-step() {
+ echo "-----> $@"
+}
+
+puts-step "Installing setuptools"
+pip install setuptools | indent
+
+puts-step "Installing Doorstop"
+python setup.py install | indent
+
+puts-step "Generating HTML from requirements"
+touch .mockvcs
+doorstop publish all public | indent
diff --git a/bin/verchew b/bin/verchew
new file mode 100755
index 000000000..359e69f13
--- /dev/null
+++ b/bin/verchew
@@ -0,0 +1,217 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+# The MIT License (MIT)
+# Copyright © 2016, Jace Browning
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+
+from __future__ import unicode_literals
+
+import os
+import sys
+import argparse
+try:
+ import configparser # Python 3
+except ImportError:
+ import ConfigParser as configparser # Python 2
+from collections import OrderedDict
+from subprocess import Popen, PIPE, STDOUT
+import logging
+
+__version__ = '1.0'
+
+PY2 = sys.version_info[0] == 2
+CONFIG_FILENAMES = ['.verchew', '.verchewrc', 'verchew.ini', '.verchew.ini']
+STYLE = {
+ "x": "✘",
+ "~": "✔"
+}
+COLOR = {
+ "x": "\033[91m", # red
+ "~": "\033[92m", # green
+ None: "\033[0m", # reset
+}
+
+log = logging.getLogger(__name__)
+
+
+def main():
+ args = parse_args()
+ configure_logging(args.verbose)
+
+ log.debug("PWD: %s", os.getenv('PWD'))
+ log.debug("PATH: %s", os.getenv('PATH'))
+
+ path = find_config(args.root)
+ config = parse_config(path)
+
+ if not check_dependencies(config) and args.exit_code:
+ sys.exit(1)
+
+
+def parse_args():
+ parser = argparse.ArgumentParser()
+
+ version = "%(prog)s v" + __version__
+ parser.add_argument('--version', action='version', version=version)
+ parser.add_argument('-v', '--verbose', action='count', default=0,
+ help="enable verbose logging")
+ parser.add_argument('-r', '--root', metavar='PATH',
+ help="specify a custom project root directory")
+ parser.add_argument('--exit-code', action='store_true',
+ help="return a non-zero exit code on failure")
+
+ args = parser.parse_args()
+
+ return args
+
+
+def configure_logging(count=0):
+ if count == 0:
+ level = logging.WARNING
+ elif count == 1:
+ level = logging.INFO
+ else:
+ level = logging.DEBUG
+
+ logging.basicConfig(level=level, format="%(levelname)s: %(message)s")
+
+
+def find_config(root=None, config_filenames=None):
+ root = root or os.getcwd()
+ config_filenames = config_filenames or CONFIG_FILENAMES
+
+ path = None
+ log.info("Looking for config file in: %s", root)
+ log.debug("Filename options: %s", ", ".join(config_filenames))
+ for filename in os.listdir(root):
+ if filename in config_filenames:
+ path = os.path.join(root, filename)
+ log.info("Found config file: %s", path)
+ return path
+
+ msg = "No config file found in: {0}".format(root)
+ raise RuntimeError(msg)
+
+
+def parse_config(path):
+ data = OrderedDict()
+
+ log.info("Parsing config file: %s", path)
+ config = configparser.ConfigParser()
+ config.read(path)
+
+ for section in config.sections():
+ data[section] = OrderedDict()
+ for name, value in config.items(section):
+ data[section][name] = value
+
+ return data
+
+
+def check_dependencies(config):
+ success = []
+
+ for name, settings in config.items():
+ show("Checking for {0}...".format(name), head=True)
+ output = get_version(settings['cli'], settings.get('cli_version_arg'))
+ if match_version(settings['version'], output):
+ show(_("~") + " MATCHED: {0}".format(settings['version']))
+ success.append(_("~"))
+ else:
+ show(_("x") + " EXPECTED: {0}".format(settings['version']))
+ success.append(_("x"))
+
+ show("Results: " + " ".join(success), head=True)
+
+ return _("x") not in success
+
+
+def get_version(program, argument=None):
+ argument = argument or '--version'
+ args = [program, argument]
+
+ show("$ {0}".format(" ".join(args)))
+ output = call(args)
+ show(output.splitlines()[0])
+
+ return output
+
+
+def match_version(pattern, output):
+ return output.startswith(pattern) or " " + pattern in output
+
+
+def call(args):
+ try:
+ process = Popen(args, stdout=PIPE, stderr=STDOUT)
+ except OSError:
+ log.debug("Command not found: %s", args[0])
+ output = "sh: command not found: {0}".format(args[0])
+ else:
+ raw = process.communicate()[0]
+ output = raw.decode('utf-8').strip()
+ log.debug("Command output: %r", output)
+
+ return output
+
+
+def show(text, start='', end='\n', head=False):
+ """Python 2 and 3 compatible version of print."""
+ if head:
+ start = '\n'
+ end = '\n\n'
+
+ if log.getEffectiveLevel() < logging.WARNING:
+ log.info(text)
+ else:
+ formatted = (start + text + end)
+ if PY2:
+ formatted = formatted.encode('utf-8')
+ sys.stdout.write(formatted)
+ sys.stdout.flush()
+
+
+def _(word, is_tty=None, supports_utf8=None, supports_ansi=None):
+ """Format and colorize a word based on available encoding."""
+ formatted = word
+
+ if is_tty is None:
+ is_tty = hasattr(sys.stdout, 'isatty') and sys.stdout.isatty()
+ if supports_utf8 is None:
+ supports_utf8 = sys.stdout.encoding == 'UTF-8'
+ if supports_ansi is None:
+ supports_ansi = sys.platform != 'win32' or 'ANSICON' in os.environ
+
+ style_support = supports_utf8
+ color_support = is_tty and supports_ansi
+
+ if style_support:
+ formatted = STYLE.get(word, word)
+
+ if color_support and COLOR.get(word):
+ formatted = COLOR[word] + formatted + COLOR[None]
+
+ return formatted
+
+
+if __name__ == '__main__': # pragma: no cover
+ main()
diff --git a/docs/cli/reordering.md b/docs/cli/reordering.md
new file mode 100644
index 000000000..c0bf26116
--- /dev/null
+++ b/docs/cli/reordering.md
@@ -0,0 +1,63 @@
+# Documents Headings
+
+The items in a document are arranged according to their level attribute, with levels ending in .0
+creating headings and the subsequent items forming sub headings.
+
+A document can contain an arbitraty number of headings and sub headings.
+
+A normative heading item will display the item's uid as the heading text. A non normative heading
+displays the first line of the item text, with any subsequent text displayed in the body of the heading.
+
+
+# Automatic item reordering
+
+Items in a document can be automatically reordered to remove gaps or duplicate entries in item headings.
+
+```sh
+$ doorstop reorder --auto REQ
+building tree...
+reordering document REQ...
+reordered document: REQ
+```
+
+# Manual item reordering
+
+Manual reordering creates an index.yml file in the document directory which describes the desired outline
+of the document. The index.yml is edited, changing the indentation and order of the items to update the
+levels of each item.
+
+```sh
+$ doorstop reorder --tool vi REQ
+building tree...
+reorder from 'reqs/index.yml'? [y/n] y
+reordering document REQ...
+reordered document: REQ
+```
+## Adding a new item
+
+An item can be added by adding a new line to the index.yml containing an unknown UID, e.g. new.
+A comment following the new item ID can be used to set the item text.
+If the line after a new item is further indented the item is treated as a heading and marked
+as non normative.
+
+```yaml
+###############################################################################
+# THIS TEMPORARY FILE WILL BE DELETED AFTER DOCUMENT REORDERING
+# MANUALLY INDENT, DEDENT, & MOVE ITEMS TO THEIR DESIRED LEVEL
+# A NEW ITEM WILL BE ADDED FOR ANY UNKNOWN IDS, i.e. - new:
+# THE COMMENT WILL BE USED AS THE ITEM TEXT FOR NEW ITEMS
+# CHANGES WILL BE REFLECTED IN THE ITEM FILES AFTER CONFIRMATION
+###############################################################################
+
+initial: 1.0
+outline:
+ - REQ018: # Overview
+ - REQ019: # Doorstop is a requirements management tool that leverage...
+ - NEW: # The text of a new item
+ - NEW: # A new heading
+ - NEW: # The text of a new ite,
+```
+
+## Deleting an item
+
+Deleting a line from index.yml will result in the item being deleted.
diff --git a/docs/reference/items.md b/docs/reference/items.md
new file mode 100644
index 000000000..e05789719
--- /dev/null
+++ b/docs/reference/items.md
@@ -0,0 +1,194 @@
+# Overview
+
+Doorstop items are files formatted using YAML. When a new item is added using
+```doorstop add```, Doorstop will create a YAML file and populate it with all
+required attributes (key-value pairs).
+
+Example item:
+```yaml
+active: true
+derived: false
+level: 2.1
+normative: true
+reviewed: 1f33605bbc5d1a39c9a6441b91389e88
+links: []
+ref: ''
+text: |
+ Doorstop **shall** provide unique and permanent identifiers to linkable
+ sections of text.
+```
+
+## Standard attributes
+
+### active
+
+Determines if the item is active (true) or not (false). Only active items are
+included when the corresponding document is published. Inactive items are
+excluded from validation.
+
+### derived
+
+Indicates if the item is derived (true) or not (false).
+
+[AcqNotes](http://www.acqnotes.com/acqnote/tasks/derived-requirements) defines derived requirements as:
+
+> '...requirements that are not explicitly stated in the set of stakeholder requirements yet is required to satisfy one or more of them. They also arise from constraints, consideration of issues implied but not explicitly stated in the requirements baseline, factors introduced by the selected architecture, Information Assurance (IA) requirements and the design.'
+
+Doorstop does not expect parent links on derived items.
+
+### normative
+
+Indicates if the item is normative (true) or non-normative (false).
+
+[Wikipedia on Normative](https://en.wikipedia.org/wiki/Normative) in standards documents:
+> 'In standards terminology still used by some organizations, "normative" means
+> "considered to be a prescriptive part of the standard". It characterizes
+> that part of the standard which describes what ought (see philosophy above) to
+> be done within the application of that standard. It is implicit that
+> application of that standard will result in a valuable outcome (ibid.). For
+> example, many standards have an introduction, preface, or summary that is
+> considered non-normative, as well as a main body that is considered normative.
+> "Compliance" is defined as "complies with the normative sections of the
+> standard"; an object that complies with the normative sections but not the
+> non-normative sections of a standard is still considered to be in compliance.'
+
+### level
+
+Indicates the presentation order within a document. A level of 1.1 will display
+above level 1.2 and 1.1.5 displays below 1.1.2.
+
+If the level ends with .0 and the item is non-normative, Doorstop will treat the
+item as a document heading. See the [text](items.md#text)-section for an
+example.
+
+### reviewed
+
+Indicates the fingerprint of the item when it was last reviewed. "null" if the
+item has not yet been reviewed. Doorstop will use this to detect unreviewed
+changes to an item by comparing the current item fingerprint to the last
+reviewed fingerprint.
+
+You should not calculate this value manually, use ```doorstop review```.
+
+
+### links
+
+A list of links to parent item(s). A link indicates a relationship between two
+items in the document tree.
+
+In the following example, ```REQ001``` is a parent to the item.
+
+```yaml
+links:
+- REQ001: 1f33605bbc5d1a39c9a6441b91389e88
+```
+
+A link consists of two parts, the parent item UID and the fingerprint of the
+parent when it last reviewed. If the link has not yet been reviewed, the
+fingerprint is set to "null" or omitted.
+
+```yaml
+links:
+- REQ001: null
+```
+
+is equivalent to
+
+```yaml
+links:
+- REQ001
+```
+
+In the cases where no fingerprint exists or a null-fingerprint is specified,
+Doorstop will add a new fingerprint whenever a review occurs.
+
+The link fingerprint is used by Doorstop to detect when a parent item is
+changed, as a convenience to the writer since such change may also affect its
+children.
+
+### ref
+
+External reference. An item may reference an external file or a line in an
+external file. An external reference is displayed in a published document.
+
+Doorstop will search the project root and it's sub-directories for a filename
+matching the specified reference. If multiple matching files exist, the first
+found will be used.
+
+If a file is not found, Doorstop will also search the contents of all text-files
+in the project root and it's sub-directories. If a line contains the referenced
+keyword, Doorstop will reference the file and line number where it found the
+keyword. If the keyword is found in multiple lines or files, the first found
+will be used.
+
+A file is considered a text-file unless its file extension is listed in
+```SKIP_EXTS``` (settings.py).
+
+#### Example: Reference keyword
+```yaml
+ref: 'TST001'
+```
+
+References the filename and line number of a text-file that contains the
+keyword "TST001".
+
+#### Example: Reference file
+```yaml
+ref: 'test-tst001.c'
+```
+
+References a file called "test-tst001.c".
+
+If a reference is specified and Doorstop is unable to find it, Doorstop will
+exit with an error unless reference checking is disabled.
+
+
+### text
+
+Item text. This is the main body of the item. Doorstop treats the value as
+markdown to support rich text, images and tables. To specify a multi-line text,
+use block scalar types as specified by the YAML standard.
+
+#### Example: Heading
+
+REQ001.yml
+```yaml
+level: 1.1.0
+normative: false
+text: |
+ This is the heading
+
+ This is some text that goes into chapter 1.1.0.
+```
+
+When this item is published, Doorstop will create a new heading with the text
+"1.1.0 This is the heading" and put the remaining text into its body.
+
+#### Example: Normative item
+
+REQ001.yml
+```yaml
+level: 1.1.0
+normative: true
+text: |
+ Doorstop **shall** support exporting to the ReqIF file format.
+```
+
+When this item is published, Doorstop will create a new heading with the text
+"1.1.0 REQ001" and put the all of the text in its body.
+
+## Extended attributes
+
+In addition to the standard attributes, Doorstop will allow any number of
+custom attributes (key-value pairs) in the YAML file. The extended attributes
+will not be part of a published document, but they can be queried by a 3rd party
+application through the REST interface or the Python API.
+
+#### Example:
+
+In this example, an extended attribute ```invented-by``` is added to the item.
+
+```yaml
+invented-by: some.guy@email.com
+```
+
diff --git a/docs/reference/webserver.md b/docs/reference/webserver.md
new file mode 100644
index 000000000..929f9cbbf
--- /dev/null
+++ b/docs/reference/webserver.md
@@ -0,0 +1,30 @@
+# Using the Doorstop web front-end
+
+## Conventional bottle webserver
+
+Doorstop can be run as a standalone web server by running
+`doorstop-server`. It will use the current working directory as the
+document source by default.
+
+## WSGI
+
+Doorstop can also be used as a WSGI application by Apache or other web
+servers. To configure this, copy 'bin/example-adapter.wsgi' from this
+repository to an appropriate place in your web data directory, such as
+'/var/www/doorstop/adapter.wsgi'. Edit that file to give it the
+correct path to your doorstop installation. Now alter your apache
+configuration and add something similar to this:
+
+ WSGIDaemonProcess doorstop user=www-data group=www-data processes=1 threads=5
+
+ WSGIScriptAlias /doorstop /var/www/doorstop/adapter.wsgi
+ | t |
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod -tempor incididunt ut labore et dolore magna aliqua. -Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut -aliquip ex ea commodo consequat. -Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore -eu fugiat nulla pariatur. -Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia -deserunt mollit anim id est laborum.
-Links: SYS001, SYS002
-Unicode: -40° ±1%
----
external/text.txt(line 3)
Links: REQ001
-Hello, world!
-Hello, world!
-Hello, world!
-Links: REQ001
- -