Merge pull request #518 from JustinW80/update-docs

Update docs

docs/cli/creation.md

@@ -6,6 +6,7 @@ A document can be created inside a directory that is under version control:
 $ doorstop create REQ ./reqs
 created document: REQ (@/reqs)
 ```
+
 Note: Only one root parent requirements document is allowed per version controlled directory.
 
 Items can be added to the document and edited:
@@ -58,6 +59,7 @@ building tree...
 ```
 
 defaults.yml
+
 ```yaml
 text: 'My default text.'
 ```
@@ -167,6 +169,7 @@ to the directory of the file with the include tag.  Absolute paths are not
 supported.  Please have a look at this example:
 
 .doorstop.yml
+
 ```yaml
 settings:
   digits: 3
@@ -178,6 +181,7 @@ attributes:
 ```
 
 path/to/file.yml
+
 ```yaml
 |
   Some template text, which may

docs/cli/reordering.md

@@ -6,7 +6,7 @@ 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. 
+displays the first line of the item text, with any subsequent text displayed in the body of the heading.
 
 
 # Automatic item reordering
@@ -22,8 +22,8 @@ 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 
+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
@@ -33,18 +33,19 @@ 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. 
+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: 
+# 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
 ###############################################################################

docs/getting-started/installation.md

@@ -0,0 +1,29 @@
+<h1> Installation </h1>
+
+Doorstop requires [Python](https://www.python.org/) v3.5+ and [Git](https://git-scm.com/) or other version control system.
+
+Once Python is installed on your platform, install Doorstop using pip.
+
+```sh
+pip install doorstop
+```
+
+or add it to your [Poetry](https://poetry.eustace.io/) project:
+
+```sh
+$ poetry add doorstop
+```
+
+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__
+```

docs/getting-started/quickstart.md

@@ -0,0 +1,68 @@
+<h1> Quickstart </h1>
+
+Help with Doorstop:
+
+- `doorstop --help`
+- `doorstop <COMMAND> --help`
+
+Set up a repository for controlling documents:
+
+- `mkdir /path/to/docs`
+- `cd /path/to/docs`
+- `git init`
+
+Create a root parent requirements document:
+
+- `doorstop create REQ ./reqs/req`
+
+Add items to a document, will be automatically numbered:
+
+- `doorstop add REQ`
+
+Create a child document (low level requirements) to link to the parent:
+
+- `doorstop create LLR ./reqs/llr --parent REQ`
+- `doorstop add LLR`
+
+Link low level items to requirements (separators like '-' are optional and ignored):
+
+- `doorstop link LLR001 REQ001`
+
+Check integrity of the document tree and validate links:
+
+- `doorstop`
+
+Mark an unreviewed item, document, or all documents as reviewed:
+
+- `doorstop review REQ-001    # Marks item REQ-001 as reviewed`
+- `doorstop review REQ        # Marks all items in document REQ as reviewed`
+- `doorstop review all        # Marks all documents as reviewed`
+
+Mark suspect links in an item, document, or all documents, as cleared:
+
+- `doorstop clear LLR-001         # Marks all links originating in item LLR-001 as cleared`
+- `doorstop clear LLR-001 REQ     # Marks links in item LLR-001 to document REQ as cleared`
+- `doorstop clear LLR REQ         # Marks all links from LLR that target REQ as cleared`
+- `doorstop clear LLR all         # Marks all links originating in document LLR as cleared`
+- `doorstop clear all             # Marks all links in all documents as cleared`
+
+Create an HTML document in `publish`:
+
+- `doorstop publish all ./publish`
+
+View in the graphical user interface (GUI):
+
+- `doorstop-gui`
+
+Browse the doc tree on a local web server:
+
+- `doorstop-server`
+- Point browser to: http://127.0.0.1:7867/
+- Ctrl+C to quit the server.
+
+Round-trip to Excel:
+
+- `doorstop export -x REQ REQ.xslx`
+- Make edits in Excel. Do not edit UIDs. Leave UID cells blank for new items.
+- `doorstop import REQ.xslx REQ`
+- `rm REQ.xlsx`

docs/setup.md → docs/getting-started/setup.md

@@ -6,7 +6,7 @@ Doorstop will open files using the editor specified by the `$EDITOR` environment
 
 **Linux / macOS**
 
-No additional configuration should be neccesary.
+No additional configuration should be necessary.
 
 **Windows**
 

docs/reference/document.md

@@ -1,3 +1,99 @@
 <h1>Document Reference</h1>
 
-> Help wanted! Please [contribute to this documentation](https://github.com/doorstop-dev/doorstop/edit/develop/docs/reference/document.md).
+Doorstop documents are folders, with metadata stored in a configuration YAML
+file `.doorstop.yml` directly below the folder.
+
+# Standard Document Attributes
+
+Upon [creation](../cli/creation.md), `.doorstop.yml` contains default settings.
+
+```sh
+$ doorstop create REQ ./reqs
+created document: REQ (@/reqs)
+```
+
+Then open `REQ/.doorstop.yml` in any text editor:
+
+```yaml
+settings:
+  digits: 3
+  prefix: REQ
+  sep: ''
+```
+
+## `settings`
+
+Parameters that affect the entire document fall under here.
+
+### `digits`
+
+Defines the number of digits in an item UID. The default value is 3. Optionally,
+you can set it through the `-d` command line option of the `doorstop create`
+command.  It is a mandatory and read-only document setting.
+
+### `parent`
+
+Defines the parent document prefix.  You set it through the `-p` command line
+option of the `doorstop create` command.  It is an optional and read-only
+document setting.
+
+### `prefix`
+
+Defines the document prefix.  You set it through the prefix of the
+`doorstop create` command.  It is a mandatory and read-only document setting.
+
+### `sep`
+
+Defines the separator between the document prefix and the number in an item UID.
+The default value is the empty string.  You have to set it manually before an
+item is created.  Afterwards, it should be considered as read-only.  This
+document setting is mandatory.
+
+# Extended Document Attributes
+
+In addition to the standard attributes, Doorstop will allow any number of custom
+extended 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.
+
+## `attributes`
+
+Extended document attributes fall under here.
+
+### `defaults`
+
+Defines the [defaults for extended
+attributes](item.md#defaults-for-extended-attributes). This is an optional
+document configuration option.
+
+### `reviewed`
+
+Defines which [extended attributes contribute to the item
+fingerprint](item.md#extended-reviewed-attributes). This is an optional document
+configuration option.
+
+In the document configuration files, you can include other YAML files through a
+value tagged with `!include`.  The path to the included file is always relative
+to the directory of the file with the include tag.  Absolute paths are not
+supported.  Please have a look at this example:
+
+In `.doorstop.yml`:
+
+```yaml
+settings:
+  digits: 3
+  prefix: REQ
+  sep: ''
+attributes:
+  defaults:
+    text: !include path/to/file.yml
+```
+
+In `path/to/file.yml`:
+
+```yaml
+|
+  Some template text, which may
+  have several
+  lines.
+```