### Install Doorstop with Pip

Source: https://github.com/doorstop-dev/doorstop/blob/develop/README.md

Install the Doorstop package using pip. This command is used for initial setup.

```sh
$ pip install doorstop
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/about/contributing.md

Installs all necessary project dependencies within a virtual environment. This is a prerequisite for development.

```shell
make install
```

--------------------------------

### Start Graphical User Interface

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/getting-started/quickstart.md

Launch the graphical user interface for Doorstop.

```bash
doorstop-gui
```

--------------------------------

### Get Help

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/getting-started/quickstart.md

Display help information for Doorstop commands.

```bash
doorstop --help
doorstop <COMMAND> --help
```

--------------------------------

### Install Doorstop Pre-release using pip

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/getting-started/installation.md

To install a pre-release version of Doorstop, use the `--pre` option with pip.

```sh
$ pip install --pre doorstop
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/doorstop-dev/doorstop/blob/develop/CONTRIBUTING.md

Installs all necessary project dependencies within a virtual environment. This should be run after verifying system dependencies.

```sh
$ make install
```

--------------------------------

### Install MiKTeX on Windows

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/getting-started/setup.md

Use winget to install MiKTeX for LaTeX publishing on Windows. This is required for PDF output.

```powershell
winget install MiKTeX.MiKTeX
```

--------------------------------

### Verify System Dependencies

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/about/contributing.md

Run this command to ensure all system dependencies are correctly configured before proceeding with installation.

```shell
make doctor
```

--------------------------------

### Local Install for External Testing

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/about/contributing.md

Installs the project locally in a way that allows for external testing, useful for verifying changes before integration.

```shell
make dev-install
```

--------------------------------

### YAML Configuration with Included File

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/cli/creation.md

Example of a .doorstop.yml file demonstrating the use of the !include tag to embed content from another YAML file.

```yaml
settings:
  digits: 3
  prefix: REQ
  sep: ''
attributes:
  defaults:
    text: !include path/to/file.yml
```

```yaml
| 
  Some template text, which may
  have several
  lines.
```

--------------------------------

### Start Local Web Server

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/getting-started/quickstart.md

Run a local web server to browse the document tree. Point your browser to http://127.0.0.1:7867/. Press Ctrl+C to quit.

```bash
doorstop-server
```

--------------------------------

### Install LaTeX on Debian/Ubuntu

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/getting-started/setup.md

Install necessary LaTeX packages for PDF publishing on Debian/Ubuntu systems using apt-get.

```sh
sudo apt-get update
sudo apt-get install texlive-latex-base texlive-latex-extra
```

--------------------------------

### Install Java, PlantUML, and Inkscape on Debian/Ubuntu

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/getting-started/setup.md

Install Java Runtime, PlantUML, and Inkscape on Debian/Ubuntu systems using apt-get for PlantUML diagram support in LaTeX.

```sh
sudo apt-get update
sudo apt-get install default-jre plantuml inkscape
```

--------------------------------

### Launch Doorstop GUI

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/gui/overview.md

Run this command in your terminal to launch the experimental Doorstop desktop GUI. Ensure Doorstop is installed and accessible in your PATH.

```sh
$ doorstop-gui
```

--------------------------------

### Verify System Dependencies

Source: https://github.com/doorstop-dev/doorstop/blob/develop/CONTRIBUTING.md

Run this command to ensure all system dependencies are correctly configured before proceeding with installation.

```sh
$ make doctor
```

--------------------------------

### Verify pdflatex installation

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/getting-started/setup.md

Check if the pdflatex command is available after installing a LaTeX distribution.

```sh
pdflatex --version
```

--------------------------------

### Install Java, PlantUML, and Inkscape on macOS

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/getting-started/setup.md

Install OpenJDK, PlantUML, and Inkscape on macOS using Homebrew for PlantUML diagram integration with LaTeX.

```sh
brew install openjdk plantuml inkscape
```

--------------------------------

### Local Install for External Testing

Source: https://github.com/doorstop-dev/doorstop/blob/develop/CONTRIBUTING.md

Installs the project locally in a way that allows for external testing, useful for verifying changes before integration.

```sh
$ make dev-install
```

--------------------------------

### Install Java, PlantUML, and Inkscape on Windows

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/getting-started/setup.md

Install required tools for PlantUML diagrams in LaTeX on Windows using winget. This includes Java Runtime, PlantUML, and Inkscape for SVG to PDF conversion.

```powershell
# Install Java Runtime (required for PlantUML)
winget install EclipseAdoptium.Temurin.17.JRE

# Install PlantUML
winget install PlantUML.PlantUML

# Install Inkscape (for SVG to PDF conversion)
winget install Inkscape.Inkscape
```

--------------------------------

### Example Published Markdown with Attributes

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/cli/publishing.md

Provides an example of how a requirement with custom attributes would be rendered in the final published document.

```markdown
### 1.2.5 SYSTEM-REQ-007 {#SYSTEM-REQ-007}

Steamboat Willie **shall** whistle while he is driving his boat.

| Attribute   | Value                                                                                         |
| ----------- | --------------------------------------------------------------------------------------------- |
| commentary  | The song should be a happy tune                                                               |
| rationale   | Whistling will help demonstrate that Steamboat Willie is having a good time and is care-free. |
| invented-by | Donald                                                                                        |
```

--------------------------------

### Install LaTeX on macOS

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/getting-started/setup.md

Install the mactex package for LaTeX publishing on macOS using Homebrew.

```sh
brew install --cask mactex
```

--------------------------------

### YAML Item Format Example

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/reference/item.md

An example of a requirement item stored in the YAML format. This format stores all attributes directly in a YAML structure.

```yaml
active: true
derived: false
header: |
  Identifiers
level: 2.1
links: []
normative: true
ref: ''
reviewed: 9TcFUzsQWUHhoh5wsqnhL7VRtSqMaIhrCXg7mfIkxKM=
text: |
  Doorstop **shall** provide unique and permanent identifiers to linkable
  sections of text.

```

--------------------------------

### Verify PlantUML dependencies

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/getting-started/setup.md

Verify that Java, PlantUML, and Inkscape are installed and accessible from the command line.

```sh
java -version
plantuml -version
inkscape --version
```

--------------------------------

### External References Example

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/reference/item.md

Specifies an array of external files that an item references. Doorstop searches the project root for matching files.

```yaml
references:
  - path: tests/test1.cpp
    type: file
  - path: tests/test2.cpp
    type: file
```

--------------------------------

### Add Doorstop to Poetry Project

Source: https://github.com/doorstop-dev/doorstop/blob/develop/README.md

Add Doorstop as a dependency to your project managed by Poetry. Ensure Poetry is installed and configured.

```sh
$ poetry add doorstop
```

--------------------------------

### Markdown Item Format Example

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/reference/item.md

An example of a requirement item stored in the Markdown format. This format uses YAML frontmatter for attributes and Markdown for the content.

```text
---
active: true
derived: false
level: 2.1
links: []
normative: true
ref: ''
reviewed: 9TcFUzsQWUHhoh5wsqnhL7VRtSqMaIhrCXg7mfIkxKM=
---

# Identifiers

Doorstop **shall** provide unique and permanent identifiers to linkable 
sections of text.

```

--------------------------------

### Get Doorstop Version

Source: https://github.com/doorstop-dev/doorstop/blob/develop/README.md

Import the Doorstop package in a Python interpreter to access and print its version number.

```python
>>> import doorstop
>>> doorstop.__version__
```

--------------------------------

### Git Line Ending Warnings Example

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/getting-started/setup.md

Example of warnings that may appear on Windows due to line ending differences between Git and the operating system.

```bash
(doorstop) C:\temp\doorstop>doorstop reorder --auto TS
building tree...
reordering document TS...
warning: LF will be replaced by CRLF in tests/sys/TS003.yml.
The file will have its original line endings in your working directory.
warning: LF will be replaced by CRLF in tests/sys/TS001.yml.
The file will have its original line endings in your working directory.
warning: LF will be replaced by CRLF in tests/sys/TS002.yml.
The file will have its original line endings in your working directory.
warning: LF will be replaced by CRLF in tests/sys/TS004.yml.
The file will have its original line endings in your working directory.
reordered document: TS
```

--------------------------------

### Default Attributes YAML Configuration

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/cli/creation.md

Example `defaults.yml` file to specify default attributes for new items.

```yaml
text: 'My default text.'
```

--------------------------------

### Item Header Example

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/reference/item.md

Defines an item with a header, which is displayed alongside the item UID in published documents. This is distinct from a heading item.

```yaml
level: 1.5
normative: true
links:
- REQ023: null
header: |
    Gradual Temperature Drop Test
text: |
    Lower the external air temperature gradually from 0 to -15 degrees Celsius over a period of 30 minutes.
    Ensure the system performs a safe shutdown when -15 degrees Celsius is reached.
```

--------------------------------

### LaTeX Math Expressions

Source: https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/core/tests/files/published.html

Examples of rendering mathematical expressions using LaTeX syntax within a document. Includes inline, parenthesized inline, and multiline display math.

```latex
Inline Style 1: $a \ne 0$ Inline Style 2: (ax^2 + bx + c = 0) Multiline: $$x = {-b \pm \sqrt{b^2-4ac} \over 2a}.$$
```

--------------------------------

### Normative 'text' Attribute Example

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/reference/item.md

Use the 'text' attribute for normative items, including rich text formatting. Doorstop will create a heading and include the formatted text in the item's body.

```yaml
level: 1.1.0
normative: true
text: |
    Doorstop **shall** support exporting to the ReqIF file format.
```

--------------------------------

### PlantUML diagram with title attribute

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/getting-started/setup.md

Example of a PlantUML code block that includes the required 'title' attribute for proper filename generation during LaTeX publishing.

```markdown
```plantuml title="System Architecture"
@startuml
Alice -> Bob: Hello
@enduml
```
```

--------------------------------

### Initialize Doorstop Repository

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/getting-started/quickstart.md

Set up a new directory and initialize it as a Git repository for document control.

```bash
mkdir /path/to/docs
cd /path/to/docs
git init
```

--------------------------------

### Multi-line 'text' Attribute for Headings

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/reference/item.md

Define item text using the 'text' attribute with YAML block scalar syntax for multi-line content. This example shows how to create a heading and its body text.

```yaml
level: 1.1.0
normative: false
text: |
    This is the heading

    This is some text that goes into chapter 1.1.0.
```

--------------------------------

### Custom Extended Attribute Example

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/reference/item.md

Add custom key-value pairs as extended attributes to an item. These attributes are not published but are accessible via the REST interface or Python API.

```yaml
invented-by: jane@example.com
```

--------------------------------

### Create a New Document

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/reference/document.md

Use the `doorstop create` command to initialize a new document folder and its configuration file. The command creates a document with a specified prefix and path.

```sh
$ doorstop create REQ ./reqs
created document: REQ (@/reqs)
```

--------------------------------

### Build Documentation

Source: https://github.com/doorstop-dev/doorstop/blob/develop/CONTRIBUTING.md

Generates the project's documentation. Ensure this is run before submitting changes.

```sh
$ make docs
```

--------------------------------

### Initialize Git Repository

Source: https://github.com/doorstop-dev/doorstop/blob/develop/README.md

Initialize a new Git repository in the current directory. This is a prerequisite for using Doorstop with version control.

```sh
$ git init .
```

--------------------------------

### Create Root Parent Document

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/getting-started/quickstart.md

Create the main requirements document using the 'create' command.

```bash
doorstop create REQ ./reqs/req
```

--------------------------------

### Build Documentation

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/about/contributing.md

Generates the project's documentation. Ensure this is run before committing changes that affect documentation.

```shell
make docs
```

--------------------------------

### Build Document Tree in REPL

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/api/scripting.md

Use this snippet to load your Doorstop documents into a Python REPL or notebook for interactive analysis.

```python
>>> import doorstop
>>> tree = doorstop.build()
>>> tree
<Tree REQ <- [ TUT <- [ HLT ], LLT ]>
>>> len(tree.documents)
4
>>> document = tree.find_document('REQ')
>>> document
Document('/Users/Browning/Documents/doorstop/reqs')
>>> sum(1 for item in document if item.active)
18
```

--------------------------------

### Build Distribution Package

Source: https://github.com/doorstop-dev/doorstop/wiki/home

Use this command to ensure the package is ready for release.

```bash
$ make dist
```

--------------------------------

### Upload Package

Source: https://github.com/doorstop-dev/doorstop/wiki/home

Use this command to upload the distribution package.

```bash
$ make upload
```

--------------------------------

### Configuring Attributes for Publishing

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/cli/publishing.md

Demonstrates how to specify which attributes should be included in the published output by modifying the .doorstop.yml file.

```yaml
settings:
  digits: 3
  prefix: SYSTEM-REQ
  sep: '-'
attributes:
  publish:
    - commentary
    - rationale
    - invented-by
```

--------------------------------

### Configure Apache for Doorstop WSGI Application

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/web.md

This configuration is for Apache to serve Doorstop as a WSGI application. Ensure DOORSTOP_PROJECT_DIR points to your document source and DOORSTOP_BASE_URL matches the script alias.

```apache
WSGIDaemonProcess doorstop user=www-data group=www-data processes=1 threads=5

WSGIScriptAlias /doorstop /var/www/doorstop/adapter.wsgi
<Directory /var/www/doorstop>
  SetEnv DOORSTOP_PROJECT_DIR /path/to/your/document
  SetEnv DOORSTOP_BASE_URL /doorstop
  WSGIProcessGroup doorstop
  WSGIApplicationGroup %{GLOBAL}
  Require all granted
</Directory>
```

--------------------------------

### View Doorstop Help

Source: https://github.com/doorstop-dev/doorstop/blob/develop/README.md

Display the help message for the Doorstop command-line interface to understand available commands and options.

```sh
$ doorstop --help
```

--------------------------------

### Add and Link Items

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/cli/creation.md

Add a new item to a child document and then link it to an item in its parent document using `doorstop link`. Cyclic dependencies are not allowed.

```sh
$ doorstop add TST
added item: TST001 (@/reqs/tests/TST001.yml)
```

```sh
$ doorstop link TST1 REQ1
linked item: TST001 (@/reqs/tests/TST001.yml) -> REQ001 (@/reqs/REQ001.yml)
```

--------------------------------

### Generic Scripting with Doorstop

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/api/scripting.md

Create reusable Python scripts to automate workflows by interacting with the Doorstop document tree.

```python
#!/usr/bin/env python

import doorstop

tree = doorstop.build()
document = tree.find_document('REQ')
count = sum(1 for item in document if item.active)

print(f"{count} active items in {document}")
```

--------------------------------

### Run Default Integrity Checks

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/cli/validation.md

Executes the main doorstop command to build the tree, load documents, and validate items. Displays WARNING and ERROR level messages by default.

```sh
$ doorstop
building tree...
loading documents...
validating items...

REQ
│
├── TUT
│   │
│   └── HLT
│
└── LLT
```

--------------------------------

### Include YAML File in Configuration

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/reference/document.md

Demonstrates how to include content from another YAML file into the `.doorstop.yml` configuration using the `!include` tag. The path to the included file is relative to the directory of the `.doorstop.yml` file.

```yaml
settings:
  digits: 3
  prefix: REQ
  sep: ''
attributes:
  defaults:
    text: !include path/to/file.yml
```

```yaml
|
  Some template text, which may
  have several
  lines.
```

--------------------------------

### Continuous Integration Check

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/about/contributing.md

Simulates the CI environment to report the overall build status. This command should pass before merging code.

```shell
make ci
```

--------------------------------

### Default .doorstop.yml Configuration

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/reference/document.md

The `.doorstop.yml` file contains default settings for a Doorstop document. These settings control aspects like UID formatting and item storage.

```yaml
settings:
  digits: 3
  prefix: REQ
  itemformat: yaml
  sep: ''
```

--------------------------------

### Import Requirements from a File

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/cli/interchange.md

Import requirements from a specified file into a given doorstop document. This command can be used to create new requirements or update existing ones.

```sh
$ doorstop import path/to/tst.csv TST
```

--------------------------------

### Configure Reviewed Attributes in .doorstop.yml

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/reference/item.md

Add attribute keys to the 'reviewed' list to include their values in the item fingerprint. This configuration must be edited manually.

```yaml
settings:
  digits: 3
  prefix: REQ
  sep: ''
attributes:
  reviewed:
  - type
  - verification-method
```

--------------------------------

### Publish HTML Document

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/getting-started/quickstart.md

Generate an HTML document in the specified output directory.

```bash
doorstop publish all ./publish
```

--------------------------------

### LaTeX Math Expressions in Doorstop

Source: https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/core/tests/files/published.txt

Demonstrates the use of LaTeX for rendering mathematical expressions within Doorstop documents. Supports inline and multiline styles.

```latex
$a \ne 0$
```

```latex
\(ax^2 + bx + c = 0\)
```

```latex
$$x = {-b \pm \sqrt{b^2-4ac} \over 2a}.$$
```

--------------------------------

### Import from Excel

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/getting-started/quickstart.md

Import changes from an Excel file back into the Doorstop document.

```bash
doorstop import REQ.xslx REQ
rm REQ.xlsx
```

--------------------------------

### Run Tests

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/about/contributing.md

Executes the project's test suite to verify the correctness of the code.

```shell
make test
```

--------------------------------

### Directory Structure for Assets

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/cli/publishing.md

Illustrates the expected placement of assets within the project directory for publishing.

```text
document_directory/
├── .doorstop.yml
├── assets/
│   ├── images/
│   │   ├── diagram1.png
│   │   └── screenshot.jpg
│   ├── attachments/
│   │   └── specification.pdf
│   └── other/
│       └── data.csv
└── items/
    ├── REQ001.yml
    └── REQ002.yml
```

--------------------------------

### Run Tests

Source: https://github.com/doorstop-dev/doorstop/blob/develop/CONTRIBUTING.md

Executes the project's test suite to verify the correctness of the code.

```sh
$ make test
```

--------------------------------

### Create Parent Requirements Document

Source: https://github.com/doorstop-dev/doorstop/blob/develop/README.md

Create a new parent requirements document named 'SRD' in the './reqs/srd' directory. This command initializes a new document tree.

```sh
$ doorstop create SRD ./reqs/srd
```

--------------------------------

### Add an Item to a Document

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/cli/creation.md

Use `doorstop add` to create a new item within an existing document. The item will be assigned a UID based on the document's prefix and a sequential number.

```sh
$ doorstop add REQ
added item: REQ001 (@/reqs/REQ001.yml)
```

--------------------------------

### Publish Extended Attributes in .doorstop.yml

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/reference/item.md

Include attribute keys in the 'publish' list to have their values appear in the published output. This configuration must be edited manually.

```yaml
settings:
  digits: 3
  prefix: REQ
  sep: ''
attributes:
  publish:
    - invented-by
```

--------------------------------

### Publish Document with Defaults

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/cli/creation.md

Publishing a document after adding items with default attributes shows the applied defaults.

```sh
$ doorstop publish REQ
building tree...
1.0     REQ001

        My default text.
```

--------------------------------

### Manual Item Reordering with Doorstop CLI and vi

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/cli/reordering.md

Manually reorder items by using the `doorstop reorder --tool vi` command. This command generates or prompts for an `index.yml` file, allowing you to edit the document's outline using a text editor like `vi`. Changes to indentation and item order in `index.yml` will 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
```

--------------------------------

### Create Child Document

Source: https://github.com/doorstop-dev/doorstop/blob/develop/README.md

Create a new child document named 'HLTC' in the './tests/hl' directory, linking it to the parent document 'SRD'.

```sh
$ doorstop create HLTC ./tests/hl --parent SRD
```

--------------------------------

### Publish Individual Document to LaTeX

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/cli/publishing.md

Publish a single document to LaTeX format. Note that custom filenames are not supported for LaTeX exports; configure this in your .doorstop.yml. The command automatically creates a 'compile.sh' script for PDF generation.

```sh
$ doorstop publish TUT path/to/name_here_is_ignored.tex
building tree...
publishing document TUT to '<...>/path/to/name_here_is_ignored.tex'...
WARNING: LaTeX export does not support custom file names. Change in .doorstop.yml instead.
You can now execute the file 'compile.sh' twice in the exported folder to produce the PDFs!
published: <...>/path/to/name_here_is_ignored.tex
$ cd path/to/
$ . ./compile.sh
This is pdfTeX, Version <Lots of text cut out!>
$ . ./compile.sh
This is pdfTeX, Version <Lots of text cut out!>
```

--------------------------------

### Edit an Existing Item

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/cli/creation.md

Use `doorstop edit` to open an existing item for editing. This command is typically used to launch a configured editor.

```sh
$ doorstop edit REQ1
opened item: REQ001 (@/reqs/REQ001.yml)
```

--------------------------------

### Latex Math Expressions

Source: https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/core/tests/files/published.md

Demonstrates inline and multiline math expressions using Latex syntax within a documentation context.

```latex
$a \ne 0$
```

```latex
\(ax^2 + bx + c = 0\)
```

```latex
$$x = {-b \pm \sqrt{b^2-4ac} \over 2a}.$$
```

--------------------------------

### Referencing Assets in Markdown

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/cli/publishing.md

Shows how to embed images and link to files using relative paths within your Doorstop documents.

```markdown
text: |
  The system shall process input data according to the flow diagram below:

  ![Data Flow Diagram](assets/images/diagram1.png)

  The specification is available at [this link](assets/attachments/specification.pdf)
```

--------------------------------

### Create Child Document

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/getting-started/quickstart.md

Create a child document, such as low-level requirements, linked to a parent document.

```bash
doorstop create LLR ./reqs/llr --parent REQ
doorstop add LLR
```

--------------------------------

### Publish All Documents to HTML

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/cli/publishing.md

Publish the entire collection of documents as an HTML webpage. Specify the output directory using './dist/'.

```sh
$ doorstop publish all ./dist/
```

--------------------------------

### Compare Coverage

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/about/contributing.md

Compares the current code coverage to the `develop` branch. Run this before creating a Pull Request to ensure no coverage has been lost.

```shell
make test-cover
```

--------------------------------

### Publish Documents as HTML

Source: https://github.com/doorstop-dev/doorstop/blob/develop/README.md

Publish all documents in the tree to HTML format, outputting the generated files to the './public' directory.

```sh
$ doorstop publish all ./public
```

--------------------------------

### Create a Child Document

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/cli/creation.md

Create a new document that links to a parent document using the `--parent` flag. This establishes a hierarchical relationship between documents.

```sh
$ doorstop create TST ./reqs/tests --parent REQ
created document: TST (@/reqs/tests)
```

--------------------------------

### Compare Coverage

Source: https://github.com/doorstop-dev/doorstop/blob/develop/CONTRIBUTING.md

Compares code coverage against the current `develop` branch to identify any regressions. Run this before creating a Pull Request.

```sh
$ make test-cover
```

--------------------------------

### Add Items to Document

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/getting-started/quickstart.md

Add new items to the specified document. Items will be automatically numbered.

```bash
doorstop add REQ
```

--------------------------------

### Continuous Integration Build

Source: https://github.com/doorstop-dev/doorstop/blob/develop/CONTRIBUTING.md

Runs the full suite of checks and tests as performed by the CI server. This command provides an overall build status report.

```sh
$ make ci
```

--------------------------------

### Clean Project Files

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/about/contributing.md

Removes build artifacts and other generated files, returning the project to a clean state.

```shell
make clean
```

--------------------------------

### Clean Project Files

Source: https://github.com/doorstop-dev/doorstop/blob/develop/CONTRIBUTING.md

Removes all generated build artifacts and temporary files, returning the project to a clean state.

```sh
$ make clean
```

--------------------------------

### Adding New Items in index.yml

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/cli/reordering.md

To add a new item during manual reordering, include an unknown UID (e.g., 'new') on a new line in the `index.yml` file. A comment following the new UID will be used as the item's text. Indenting subsequent lines treats the new item as a non-normative heading.

```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,
```

--------------------------------

### Run Static Analysis

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/about/contributing.md

Performs static code analysis to check for potential issues and enforce code quality standards.

```shell
make check
```

--------------------------------

### Automatic Item Reordering with Doorstop CLI

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/cli/reordering.md

Use the `doorstop reorder --auto` command to automatically reorder items in a document, removing gaps or duplicate entries in item headings. This is useful for maintaining a clean and sequential item structure.

```sh
$ doorstop reorder --auto REQ
building tree...
reordering document REQ...
reordered document: REQ
```

--------------------------------

### PlantUML Diagram for Doorstop Use Cases

Source: https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/core/tests/files/published.md

This PlantUML code generates an SVG diagram illustrating the use cases of Doorstop, including document and item management, linking, editing, reviewing, deleting, exporting, and importing.

```plantuml
@startuml
Author --> (Create Document)
Author --> (Create Item)
Author --> (Link Item to Document)
Author --> (Link Item to other Item)
Author --> (Edit Item)
Author --> (Review Item)
Author -> (Delete Item)
Author -> (Delete Document)
(Export) <- (Author)
(Import) <- (Author)
Reviewer --> (Review Item)
System --> (Suspect Changes)
System --> (Integrity)
@enduml
```

--------------------------------

### Publish Document to TST Format

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/cli/publishing.md

Use this command to publish a document to the TST format, specifying the output file path.

```sh
$ doorstop publish TST path/to/tst.md
publishing TST to path/to/tst.md...

```

--------------------------------

### Run Development Tasks Continuously

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/about/contributing.md

Keeps all development tasks, such as tests and static analysis, running automatically whenever file changes are detected.

```shell
make dev
```

--------------------------------

### Run Static Analysis

Source: https://github.com/doorstop-dev/doorstop/blob/develop/CONTRIBUTING.md

Performs static code analysis to check for potential issues and enforce coding standards.

```sh
$ make check
```

--------------------------------

### Release to PyPI

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/about/contributing.md

Uploads the project's release to the Python Package Index (PyPI). This is typically done by maintainers during a release process.

```shell
make upload
```

--------------------------------

### Mark Items as Reviewed

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/getting-started/quickstart.md

Mark specific items, documents, or all documents as reviewed.

```bash
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
```

--------------------------------

### PlantUML Diagram for Doorstop Use Cases

Source: https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/core/tests/files/published.html

This snippet defines a PlantUML diagram to illustrate the use cases of Doorstop. It is rendered inline as an SVG.

```plantuml
plantuml format="svg_inline" alt="Use Cases of Doorstop" title="Use Cases of Doorstop" @startuml Author --> (Create Document) Author --> (Create Item) Author --> (Link Item to Document) Author --> (Link Item to other Item) Author --> (Edit Item) Author --> (Review Item) Author -> (Delete Item) Author -> (Delete Document) (Export) <- (Author) (Import) <- (Author) Reviewer --> (Review Item) System --> (Suspect Changes) System --> (Integrity) @enduml
```

--------------------------------

### MathJax Configuration for LaTeX

Source: https://github.com/doorstop-dev/doorstop/blob/develop/doorstop/core/tests/files/published.html

This JavaScript configuration object sets up MathJax to render inline and display math expressions using LaTeX syntax. It specifies delimiters for both inline and display math.

```javascript
MathJax = { tex: { inlineMath: [['$', '$'], ['\\(', '\\)']], displayMath: [['$$', '$$'], ['\\\[', '\\]']] }, svg: { fontCache: 'global' } };
```

--------------------------------

### Publish Individual Document to Plain Text

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/cli/publishing.md

Use this command to publish a single document to plain text format. Replace 'TST' with your document's identifier.

```sh
$ doorstop publish TST
```

--------------------------------

### Deprecated 'ref' Attribute for File Reference

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/reference/item.md

The 'ref' attribute is deprecated. Use it to reference a specific file by its name. Doorstop searches project directories for a matching filename.

```yaml
ref: 'test-tst001.c'
```

--------------------------------

### Custom Default Extended Attributes Configuration

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/reference/item.md

Configure default values for custom extended attributes in the '.doorstop.yml' file under the 'attributes.defaults' section. This allows defining complex default structures.

```yaml
settings:
  digits: 3
  prefix: REQ
  sep: ''
attributes:
  defaults:
    attribute-key-0: a scalar default value
    attribute-key-1:
    - default values can
    - be lists
    attribute-key-2:
      default: values can
      be: dictionaries
    attribute-key-3: ... default values can be arbitrarily complex
```

--------------------------------

### Item Validation Hook per Folder

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/api/scripting.md

Implement a custom item validator in a Python file referenced in the .doorstop.yml configuration for folder-specific validation.

```python
def item_validator(item):
    if getattr(item, "references") == None:
        return [] # early return
    for ref in item.references:
        if ref['sha'] != item._hash_reference(ref['path']):
            yield DoorstopError("Hash has changed and it was not reviewed properly")
```

--------------------------------

### Custom Validation Hooks

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/api/scripting.md

Extend Doorstop's default validations by implementing custom document and item hooks in a Python script.

```python
#!/usr/bin/env python

import sys
from doorstop import build, DoorstopInfo, DoorstopWarning, DoorstopError


def main():
    tree = build()
    success = tree.validate(document_hook=check_document, item_hook=check_item)
    sys.exit(0 if success else 1)


def check_document(document, tree):
    if sum(1 for i in document if i.normative) < 10:
        yield DoorstopInfo("fewer than 10 normative items")


def check_item(item, document, tree):
    if not item.get('type'):
        yield DoorstopWarning("no type specified")
    if item.derived and not item.get('rationale'):
        yield DoorstopError("derived but no rationale")


if __name__ == '__main__':
    main()
```

--------------------------------

### New 'references' Attribute with Keywords

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/reference/item.md

Use the 'references' attribute to specify multiple file references, optionally with keywords for precise matching within files. This is the newer, more flexible behavior.

```yaml
references:
- path: tests/test1.cpp
  type: file
  keyword: REQ1
- path: tests/test2.cpp
  type: file
  keyword: REQ2
```

--------------------------------

### Link to Parent Item with Fingerprint

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/reference/item.md

Establishes a link to a parent item, including its UID and the fingerprint from its last review. This helps detect changes in parent items.

```yaml
links:
- REQ001: avwblqPimDJ2OgTrRCXxRPN8FQhUBWqPIXm7kSR95C4=
```

--------------------------------

### Publish All Documents to LaTeX

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/cli/publishing.md

Publish the entire collection of documents to LaTeX format. A 'compile.sh' script is generated for PDF compilation. The output directory is specified as './path/to/'.

```sh
$ doorstop publish --latex all path/to/
building tree...
loading documents...
publishing tree to '<...>/path/to'...
You can now execute the file 'compile.sh' twice in the exported folder to produce the PDFs!
published: <...>/path/to
$ cd path/to/
$ . ./compile.sh
This is pdfTeX, Version <Lots of text cut out!>
$ . ./compile.sh
This is pdfTeX, Version <Lots of text cut out!>
```

--------------------------------

### Referenced File with SHA256 Hash

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/reference/item.md

Includes a 'sha' field for a referenced file, generated by Doorstop when 'item_sha_required' is enabled in the configuration. This ensures the integrity of referenced files.

```yaml
active: true
derived: false
header: ""
level: 2.0
links: []
normative: true
ref: ""
references:
  - path: files/a.file
    sha: 28c16553011a46bca9b78d189f8fd30c59c4138a1b6a9a4961f525849d48037e
    type: file
reviewed: BU95pdUUcz5DrFur8GUUqBaIXSNPBYMEZVMy-6IPM4s=
text: |
  My text
```

--------------------------------

### Export Requirements to Standard Output

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/cli/interchange.md

Export requirements for a given document to standard output. This is useful for viewing requirements in a structured format or piping them to other commands.

```sh
$ doorstop export TST
TST001:
  active: true
  dervied: false
  level: 1
  links:
  - REQ001
  normative: true
  ref: ''
  text: |
    Verify the foobar will foo and bar.
```

--------------------------------

### Export to Excel

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/getting-started/quickstart.md

Export a document to an Excel file for editing. Do not edit UIDs. Leave UID cells blank for new items.

```bash
doorstop export -x REQ REQ.xslx
```

--------------------------------

### Add Items to Document

Source: https://github.com/doorstop-dev/doorstop/blob/develop/README.md

Add new items to the 'SRD' document. Each command adds a single item with an auto-generated ID.

```sh
$ doorstop add SRD
```

```sh
$ doorstop add SRD
```

```sh
$ doorstop add SRD
```

--------------------------------

### Export Requirements to a File

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/cli/interchange.md

Export requirements for a given document to a specified file path. The file extension determines the output format (e.g., .csv, .yml, .xlsx).

```sh
$ doorstop export TST path/to/tst.csv
exporting TST to path/to/tst.csv...
exported: path/to/tst.csv
```

--------------------------------

### Create Document with Custom Separator

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/cli/creation.md

Create a document with a custom separator character (e.g., '-') for UIDs using the `-s` flag.

```sh
$ doorstop create -s - REQ ./reqs
building tree...
created document: REQ (@/reqs)
```

--------------------------------

### Git Line Ending Configuration

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/getting-started/setup.md

Add this to your .gitattributes file to ensure consistent line endings (LF) for YAML files, preventing Git warnings on Windows.

```gitattributes
*.yml text eol=lf
```

--------------------------------

### Link Items Between Documents

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/getting-started/quickstart.md

Establish links between items in different documents. Separators like '-' are optional.

```bash
doorstop link LLR001 REQ001
```

--------------------------------

### Link to Parent Item without Fingerprint

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/reference/item.md

Links to a parent item where the fingerprint is omitted or set to null. Doorstop will automatically add a fingerprint upon review.

```yaml
links:
- REQ001: null
```

```yaml
links:
- REQ001
```

--------------------------------

### Publish Document with Custom UIDs

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/cli/creation.md

Publishing a document shows items with custom UIDs, including those with specified numbers or names.

```sh
$ doorstop publish REQ
building tree...
1.0     REQ-001

1.1     REQ-003

1.2     REQ-FOOBAR

1.3     REQ-004
```

--------------------------------

### Run Integrity Checks

Source: https://github.com/doorstop-dev/doorstop/blob/develop/README.md

Perform integrity checks on the entire document tree. This command validates traceability and consistency.

```sh
$ doorstop
```

--------------------------------

### Link Items Between Documents

Source: https://github.com/doorstop-dev/doorstop/blob/develop/README.md

Create a link between item 'HLTC001' in the child document and item 'SRD002' in the parent document. This establishes traceability.

```sh
$ doorstop link HLTC001 SRD002
```

--------------------------------

### Add Item with Custom Name UID

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/cli/creation.md

Specify a custom name for an item's UID using the `-n` flag. Names can only be used if the document was created with a separator and cannot contain separators themselves.

```sh
$ doorstop add -n FOOBAR REQ
building tree...
added item: REQ-FOOBAR (@/reqs/REQ-FOOBAR.yml)
```

--------------------------------

### YAML Level Formatting

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/reference/item.md

YAML's implicit typing can cause issues with numerical values like '1.10'. Use quotes to ensure correct interpretation as a string.

```yaml
level: 1.10
```

```yaml
level: '1.10'
```

--------------------------------

### Check Document Integrity

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/getting-started/quickstart.md

Verify the integrity of the document tree and validate all links.

```bash
doorstop
```

--------------------------------

### Push Changes

Source: https://github.com/doorstop-dev/doorstop/wiki/home

Push committed changes to the remote repository.

```bash
$ git push
```

--------------------------------

### Add Item with Custom Number UID

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/cli/creation.md

Specify a custom number for an item's UID using the `-n` flag. This is useful for controlling the numerical sequence.

```sh
$ doorstop add -n 3 REQ
building tree...
added item: REQ-003 (@/reqs/REQ-003.yml)
```

--------------------------------

### Add Item with Default UID (Custom Separator)

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/cli/creation.md

When a document uses a custom separator, adding items follows the default pattern including the separator.

```sh
$ doorstop add REQ
building tree...
added item: REQ-001 (@/reqs/REQ-001.yml)
```

--------------------------------

### Clear Suspect Links for an Item

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/cli/validation.md

Clears suspect links for a specific item (e.g., LLT005) using the `doorstop clear` command. This is useful when parent item fingerprints change.

```sh
doorstop
building tree...
loading documents...
validating items...
WARNING: LLT: LLT005: suspect link: REQ001

REQ
│
├── TUT
│   │
│   └── HLT
│
└── LLT
```

```sh
$ doorstop clear LLT005
building tree...
clearing item LLT005's suspect links...

```

--------------------------------

### Deprecated 'ref' Attribute for Keyword Reference

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/reference/item.md

The 'ref' attribute is deprecated. Use it to reference a keyword within text files, which will link to the file and line number where the keyword is found. This is the old behavior.

```yaml
ref: 'TST001'
```

--------------------------------

### Add Items with Custom Default Attributes

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/cli/creation.md

Specify default attribute values when adding items using the `-d` flag and a YAML file. These defaults override document configuration values.

```sh
$ doorstop add -d defaults.yml REQ
building tree...
added item: REQ001 (@/reqs/REQ001.yml)
```

--------------------------------

### Continuous Development Mode

Source: https://github.com/doorstop-dev/doorstop/blob/develop/CONTRIBUTING.md

Keeps all development tasks (tests, analysis, etc.) running automatically on file changes. Requires `terminal-notifier` for OS X notifications.

```sh
$ make dev
```

--------------------------------

### Perform Strict Child Link Checks

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/cli/validation.md

Use the --strict-child-check flag to ensure every item in a document links to its parents. This command may output WARNING messages for documents with no links from their children.

```sh
$ doorstop --strict-child-check
building tree...
loading documents...
validating items...
WARNING: REQ: REQ001: no links from document: TUT
WARNING: REQ: REQ016: no links from document: LLT
WARNING: REQ: REQ017: no links from document: LLT
WARNING: REQ: REQ008: no links from document: TUT
WARNING: REQ: REQ009: no links from document: TUT
WARNING: REQ: REQ014: no links from document: TUT
WARNING: REQ: REQ015: no links from document: TUT

REQ
│
├── TUT
│   │
│   └── HLT
│
└── LLT
```

--------------------------------

### Clear Suspect Links

Source: https://github.com/doorstop-dev/doorstop/blob/develop/docs/getting-started/quickstart.md

Mark suspect links as cleared for specific items, documents, or all documents.

```bash
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
```

--------------------------------

### Add Item to Child Document

Source: https://github.com/doorstop-dev/doorstop/blob/develop/README.md

Add a new item to the 'HLTC' document. This item will be part of the child document's tree.

```sh
$ doorstop add HLTC
```

--------------------------------

### Commit Development Version Bump

Source: https://github.com/doorstop-dev/doorstop/wiki/home

Commit changes after bumping the development version number and adding '-dev'.

```bash
$ git commit -am "Bump development version number"
```