This document is a list of questions that people ask about StrictDoc.
Missing a question or an answer? Ask it here: Contact the developers.
StrictDoc is software for writing technical requirements specifications.
StrictDoc is a spare-time open-source project developed by Stanislav Pankevich (@stanislaw) and Maryna Balioura (@mettta) with contributions from the Open Source community.
The project exists since mid-2019.
Talks:
Application of the SPDX Safety Profile in the Safety Scope of the Zephyr Project. This presentation introduces the SPDX Safety Profile and details its application within the context of the Zephyr Project. There is also a presentation of the Zephyr project’s methodology for capturing requirements using StrictDoc and a discussion of the upcoming plans for the integration of SPDX into StrictDoc.
Blog posts:
Screencasts/tutorials:
Automotive SPICE in opensource StrictDoc tool, with System Architecure ideas by Lukasz Juranek.
This question can be answered in two ways. First of all, StrictDoc has its own web server that can be run with strictdoc server .... Refer to the User Guide for further information.
The following suggestions assume that you are looking to using a web server to host the StrictDoc’s static HTML export, without using StrictDoc’s own web server.
Is your project public or private? If it is public, you could simply use GitHub pages. See how one user of StrictDoc is doing it here: nmfta-repo/vcr-experiment and the resulting static website: nmfta-repo.github.io/vcr-experiment.
A very good alternative to GitHub pages is Read the Docs.
If the project is private, you could use any server that reads HTML files from a folder. For example, Python has an embedded Web Server, see this for example. Also you could try any web server based on Node.JS.
StrictDoc is only partially compatible with Sphinx.
StrictDoc does not have Sphinx in its dependency tree, and it does not use any of Sphinx API. Instead, StrictDoc uses Docutils for RST markup support. Using Docutils, StrictDoc can generate SDoc files to RST files.
There are users of StrictDoc who use both StrictDoc and Sphinx. The following workflow is known to work:
Write some documentation in SDoc files.
Export an SDoc documentation tree to an RST documentation tree.
Connect RST documentation tree with a Sphinx setup.
Run Sphinx against an RST documentation tree, obtain a Sphinx documentation website or LaTex PDF.
There is a GitHub issue Unexpected restriction on specific RST directives / compatibility with Breathe Sphinx Plugin #1093 where a closer bridging between StrictDoc and Sphinx was discussed with no specific and actionable outcome. This comment is especially relevant as well as the one about possible implementation.
Shortly: The SDoc markup is a hybrid of TOML and YAML with some influence from HTML/XML and ASN.1. Using each of these formats as-is, and also the JSON format, was considered but discarded during the design. The SDoc markup has been pretty stable since its inception but the flexibility of the TextX parser allows easy modifications of the language in case of future evolutions. Any feedback to the current design of the markup language is appreciated.
The main use case for SDoc is to model a structure of a technical document that consists of tens and hundreds of technical requirements. The following high-level requirements for the markup are therefore relevant:
Encode documents of reasonable size (up to several hundreds or few thousands of A4-printed pages).
Visualize large blocks of requirements text without too much markup noise.
Support documents with nested (2-4 levels) or deeply nested structure (detailed technical specifications with up to 9-10 levels of chapter nesting).
Support multiple fields for requirement meta information which makes a requirement look like “a text with some meta information around it”.
SDoc format is inspired by several formats: TOML, YAML, ASN.1 and HTML/XML.
TOML: Square bracket syntax
From TOML, StrictDoc borrowed the [] bracket syntax to create the [REQUIREMENT], [SECTION] and other blocks but uses the YAML-like syntax for these blocks’ fields, for example:
[REQUIREMENT]
TITLE: Requirement ABC
STATEMENT: The system A shall do B when C.
TOML/YAML: Arrays/dictionaries
StrictDoc has a rudimentary support of arrays and dictionaries. For example, the syntax for defining the document’s [GRAMMAR] resembles what would look like an array of records in YAML:
[GRAMMAR]
ELEMENTS:
- TAG: REQUIREMENT
FIELDS:
- TITLE: UID
TYPE: String
REQUIRED: True
- TITLE: LEVEL
TYPE: String
REQUIRED: False
Capitalization of reserved keywords from ASN.1
From ASN.1, StrictDoc borrows the idea of having all reserved fields capitalized. This helps to visually distinguish between the grammar content and user content.
Nested sections
From HTML, the idea of opening and closing tags is taken to avoid any nesting that would otherwise be required to support the deeply nested documents with up to 6 or 8 levels, e.g., 1.1.1.1.1.1.1…
[SECTION]
TITLE: Section 1
[SECTION]
TITLE: Section 1.1
...
[/SECTION]
[/SECTION]
Taking HTML or XML as-is didn’t seem like a good option because of the heavy visual noise that is produced around the actual content by the surrounding tags.
Multiline strings
The support of multiline strings is arranged by a custom solution which helps to avoid any nesting of multiline text as well as to visually indicate the start and end parts of the multiline string in a visually unambiguous way. This is how the multiline string is declared:
[REQUIREMENT]
TITLE: Requirement ABC
STATEMENT: >>>
The multiline requirement statement
without any nesting.
>>>
Discarded options
Taking TOML or YAML as-is didn’t seem like a good option because these formats are designed to be used for configuration files or data serialization and not for large documents with hundreds of requirements. The most obvious problems for reusing either of TOML or YAML directly would have been with encoding the deeply nested documents and supporting readable and non-nested multiline strings.
The StrictDoc project is a close successor of another project called Doorstop.
Doorstop is a requirements management tool that facilitates the storage of textual requirements alongside source code in version control.
The author of Doorstop has published a paper about Doorstop where the rationale behind text-based requirements management is provided.
The first version of StrictDoc had started as a fork of the Doorstop project. However, after a while, the StrictDoc was started from scratch as a separate project. At this point, StrictDoc and Doorstop do not share any code but StrictDoc still shares with Doorstop their common underlying design principles:
Both Doorstop and StrictDoc are written using Python. Both are pip packages which are easy-to-install.
Both Doorstop and StrictDoc provide a command-line interface.
Both Doorstop and StrictDoc use text files for requirements management.
Both Doorstop and StrictDoc encourage collocation of code and documentation. When documentation is hosted close to code it has less chances of diverging from the actual implementation or becoming outdated.
As the free and open source projects, both Doorstop and StrictDoc seem to struggle to find resources for development of specialized GUI interfaces this is why both tools give a preference to supporting exporting documentation pages to HTML format as the primary export feature.
StrictDoc differs from Doorstop in a number of aspects:
Doorstop stores requirements in YAML files, one separate file per requirement (example). The document in Doorstop is assembled from the requirements files into a single logical document during the document generation process. StrictDoc’s documentation unit is one document stored in an .sdoc file. Such a document can have multiple requirements grouped by sections.
In YAML files, Doorstop stores requirements properties such as
normative: true or level: 2.3 for which Doorstop provides validations.
Such a design decision, in fact, assumes an existence of implicitly-defined
grammar which is encoded “ad-hoc” in the parsing and validation rules of
Doorstop.
StrictDoc takes a different approach and defines its grammar explicitly using
a tool for creating Domain-Specific Languages called textX.
TextX support allows StrictDoc to encode a strict type-safe grammar in a
single grammar file
that StrictDoc uses to parse the documentation files
using the parsing capabilities provided by textX out of the box.
The roadmap of StrictDoc contains a work item for supporting the export/import to/from Doorstop format.
Both Sphinx and StrictDoc are both documentation generators but StrictDoc is at a higher level of abstraction: StrictDoc’s specialization is requirements and specifications documents. StrictDoc can generate documentation to a number of formats including HTML format as well as the RST format which is a default input format for Sphinx. A two stage generation is therefore possible: StrictDoc generates RST documentation which then can be generated to HTML, PDF, and other formats using Sphinx.
If you are reading this documentation at
https://strictdoc.readthedocs.io/en/latest
then you are already looking at the example: this documentation stored in
strictdoc_02_faq
is converted to RST format by StrictDoc which is further converted to the HTML
website by readthedocs which uses Sphinx under the hood. The
StrictDoc -> RST -> Sphinx -> PDF example is also generated using readthedocs:
StrictDoc.
Sphinx-Needs is a text-based requirements management system based on Sphinx. It is implemented as a Sphinx extension which extends the reStructuredText (RST) markup language with an additional syntax for writing requirements documents.
Sphinx-Needs was a great source of inspiration for the second version of StrictDoc which was first implemented as a Sphinx extension and then as a more independent library on top of docutils that Sphinx uses for the underlying RST syntax processing work.
The similarities between Sphinx-Needs and StrictDoc:
In contrast to Doorstop, both Sphinx-Needs and StrictDoc do not split a document into many small files, one file per single requirement (see discussion doorstop#401). Both tools follow the “file per document” approach.
Sphinx-Needs has a
well-developed language
based on custom RST directives, such
as req::, spec::, needtable::, etc. The RST document is parsed
by Sphinx/docutils into RST abstract syntax tree (AST) which allows creating
an object graph out for the documents and their requirements from the RST
document. StrictDoc uses textX for building an AST from a SDoc document.
Essentially, both Sphinx-Needs and StrictDoc work in a similar way but use
different markup languages and tooling for the job.
The difference between Sphinx-Needs and StrictDoc:
RST tooling provided by Sphinx/docutils is very powerful, yet it can also be rather limiting. The RST syntax and underlying docutils tooling do not allow much flexibility needed for creating a language for defining requirements using a custom and explicit grammar, a feature that became a cornerstone of StrictDoc. This was a major reason why the third generation of StrictDoc started with a migration from docutils to textX which is a dedicated tool for creating custom Domain-Specific Languages. After the migration to textX, StrictDoc is no longer restricted to the limitations of the RST document but it is still possible to generate SDoc files to RST using StrictDoc and then further generate RST to HTML/PDF and other formats using Sphinx.
Sphinx-Needs has an impressive list of config options and features that StrictDoc is missing. Examples: Customizing the look of the requirements, Roles, Services and others.
FRET is a framework for the elicitation, specification, formalization and understanding of requirements.
Users enter system requirements in a specialized natural language.
FRET helps understanding and review of semantics by utilizing a variety of forms for each requirement: natural language description, formal mathematical logics, and diagrams.
Requirements can be defined in a hierarchical fashion and can be exported in a variety of forms to be used by analysis tools.
FRET has an impressive list of Publications.
FRET’s user interface is built with Electron.
The detailed comparison is coming.
The first StrictDoc commit dates back to 2019-08-10. A short development chronology of StrictDoc is as follows:
2019 – July – August
StrictDoc is a result of several attempts to find a solution for working with text-based requirements. The first version of StrictDoc had started as a fork of the Doorstop project. However, after a while, StrictDoc was started from scratch as a separate project.
2019 – August
StrictDoc, first generation, the first commit dates to 2019-08-10. Markdown-based C++ program. Custom requirements metadata in YAML.
2020 – January
StrictDoc, second generation: RST/Sphinx-based Python program. Using Sphinx extensions to manage meta information.
2020 – May
The current StrictDoc repository was created on GitHub: the first commit dates back 2020-05-14. The code still uses RST for parsing requirements meta information and PySide for GUI.
The result of these efforts was the realization that a text-based requirements and specifications management tool could be built on top of a domain-specific language (DSL) created specifically for the purpose of writing requirements and specifications documents. Such a language allows explicit definition of a document data model which is called “grammar”.
2020 – July
The custom RST parser was replaced with a TextX-based DSL. Since then, StrictDoc has been using TextX for parsing SDoc files.
2022 – November
The FastAPI/Turbo/Stimulus-based Web interface prototype was created to complement the text-based interface with a graphical user interface (GUI). When the Web-based GUI is stable, StrictDoc may become useable by non-programmers too.
Most relevant GitHub statistics:
The pip trends helps to visualize the Pip package download stats. The reqif satellite project is included for comparison as well:
strictdoc vs reqif.