Type | Level | UID | STATUS | TAGS | REFS | Title | Statement | Rationale | Comment | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Section | 1 |
Introduction
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Free text | – |
StrictDoc is software for writing technical requirements and specifications. Summary of StrictDoc features:
See the Backlog to get an idea of the overall project direction. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Section | 1.1 |
Contact the developers
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Free text | – |
Join us in Discord. Here is the invitation link: https://discord.gg/4BAAME9MmG The author can be also contacted via email. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Section | 2 |
Examples
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Free text | – |
"Hello World" example of the text language: [DOCUMENT] TITLE: StrictDoc [REQUIREMENT] UID: SDOC-HIGH-REQS-MANAGEMENT TITLE: Requirements management STATEMENT: StrictDoc shall enable requirements management. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Free text | – |
For a more comprehensive example check the source file of this documentation which is written using StrictDoc: strictdoc_01_user_guide.sdoc. Additionally, the project's repository contains a folder tests/integration/examples. In this folder, there is a collection of basic examples. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Section | 3 |
Getting started
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Section | 3.1 |
Requirements
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Free text | – |
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Section | 3.2 |
Installing StrictDoc as a Pip package (recommended way)
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Free text | – |
pip install strictdoc |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Section | 3.3 |
Installing StrictDoc into a Docker container
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Free text | – |
StrictDoc can be invoked inside of a Docker container. To make data available to the Docker container (here: strictdoc:latest) as well as to the host system, one needs to mount a volume via -v option. In the host operating system terminal: docker build . -t strictdoc:latest docker run --name strictdoc --rm -v "$(pwd)/docs:/data" -i -t strictdoc:latest In the container terminal: bash-5.1# strictdoc export . bash-5.1# exit The documentation resides in ./docs/output/html. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Section | 3.4 |
Installing StrictDoc as a Snap package (not maintained)
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Free text | – |
This way of installing StrictDoc is not maintained anymore. If you want to use it, refer to the instructions located in developer/snap/README.md. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Section | 3.5 |
Hello world
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Free text | – |
git clone --depth 1 https://github.com/strictdoc-project/strictdoc && cd strictdoc strictdoc export docs/ |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Section | 4 |
SDoc syntax
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Free text | – |
StrictDoc defines a special syntax for writing specifications documents. This syntax is called SDoc and it's grammar is encoded with the textX tool. The grammar is defined using textX language for defining grammars and is located in a single file: grammar.py. This is how a minimal possible SDoc document looks like: [DOCUMENT] TITLE: StrictDoc This documentation is written using StrictDoc. Here is the source file: strictdoc_01_user_guide.sdoc. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Section | 4.1 |
Document structure
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Free text | – |
An SDoc document consists of a [DOCUMENT] declaration followed by one or many [REQUIREMENT] or [COMPOSITE_REQUIREMENT] statements which can be grouped into [SECTION] blocks. The following grammatical constructs are currently supported:
Each construct is described in more detail below. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Section | 4.1.1 |
Strict rule #1: One empty line between all nodes
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Free text | – |
StrictDoc's grammar requires each node, such as [REQUIREMENT], [SECTION], etc., to be separated with exactly one empty line from the nodes surrounding it. This rule is valid for all nodes. Absence of an empty line or presence of more than one empty line between two nodes will result in an SDoc parsing error. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Section | 4.1.2 |
Strict rule #2: No content is allowed outside of SDoc grammar
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Free text | – |
StrictDoc's grammar does not allow any content to be written outside of the SDoc grammatical constructs. It is assumed that the critical content shall always be written in form of requirements: [REQUIREMENT] and [COMPOSITE_REQUIREMENT]. Non-critical content shall be specified using [FREETEXT] nodes. By design, the [FREETEXT] nodes can be only attached to the [DOCUMENT] and [SECTION] nodes. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Section | 4.2 |
Grammar elements
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Section | 4.2.1 |
Document
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Free text | – |
[DOCUMENT] element must always be present in an SDoc document. It is a root of an SDoc document graph. [DOCUMENT] TITLE: StrictDoc (newline) DOCUMENT declaration must always have a TITLE field. It can have optional configuration fields and an optional [FREETEXT] block. [DOCUMENT] TITLE: StrictDoc [FREETEXT] StrictDoc is software for writing technical requirements and specifications. [/FREETEXT] |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Section | 4.2.1.1 |
Option: Requirement style
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Free text | – |
The REQUIREMENT_STYLE option controls whether requirement's elements are displayed inline or as table blocks. The available options are: Inline and Table. [DOCUMENT] TITLE: Hello world OPTIONS: REQUIREMENT_STYLE: Table |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Section | 4.2.1.2 |
Option: Requirement title in Table of Contents
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Free text | – |
The REQUIREMENT_IN_TOC option controls whether requirement's title appear in the table of contents (TOC). The available options are: True/False. [DOCUMENT] TITLE: Hello world OPTIONS: REQUIREMENT_IN_TOC: True |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Section | 4.2.2 |
Requirement
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Free text | – |
Minimal "Hello World" program with 3 empty requirements: [DOCUMENT] TITLE: StrictDoc [REQUIREMENT] [REQUIREMENT] [REQUIREMENT] Supported fields:
Currently, all [REQUIREMENT]'s are optional but most of the time at least the STATEMENT: field must be present as well as the TITLE: field. [DOCUMENT] TITLE: StrictDoc [REQUIREMENT] TITLE: Requirements management STATEMENT: StrictDoc shall enable requirements management. Observation: Many real-world documents have requirements with statements and titles but some documents only use statements without title in which case their title becomes their UID. Example: [DOCUMENT] TITLE: StrictDoc [REQUIREMENT] UID: REQ-001 STATEMENT: StrictDoc shall enable requirements management. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Section | 4.2.2.1 |
UID
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Free text | – |
Observation: Some documents do not use unique identifiers which makes it impossible to trace their requirements to each other. Within StrictDoc's framework, it is assumed that a good requirements document has all of its requirements uniquely identifiable, however, the UID field is optional to accommodate for documents without connections between requirements. StrictDoc does not impose any limitations on the format of a UID. Examples of typical conventions for naming UIDs:
[DOCUMENT] TITLE: StrictDoc [REQUIREMENT] UID: SDOC-HIGH-DATA-MODEL STATEMENT: STATEMENT: StrictDoc shall be based on a well-defined data model. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Section | 4.2.2.2 |
References
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Free text | – |
The [REQUIREMENT] / REFS: field is used to connect requirements to each other: [DOCUMENT] TITLE: StrictDoc [REQUIREMENT] UID: REQ-001 STATEMENT: StrictDoc shall enable requirements management. [REQUIREMENT] UID: REQ-002 REFS: - TYPE: Parent VALUE: REQ-001 TITLE: Requirement #2's title STATEMENT: Requirement #2 statement Note: The TYPE: Parent is the only supported type of connection. In the future, linking requirements to files will be possible. Note: By design, StrictDoc will only show parent or child links if both requirements connected with a reference have UID defined. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Section | 4.2.2.3 |
Comment
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Free text | – |
A requirement can have one or more comments explaining this requirement. The comments can be single-line or multiline. [DOCUMENT] TITLE: StrictDoc [REQUIREMENT] UID: REQ-001 STATEMENT: StrictDoc shall enable requirements management. COMMENT: Clarify the meaning or give additional information here. COMMENT: >>> This is a multiline comment. The content is split via \n\n. Each line is rendered as a separate paragraph. <<< |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Section | 4.2.2.4 |
Rationale
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Free text | – |
A requirement can have a RATIONALE: field that explains why such a requirement exists. Like comments, the rationale field can be single-line or multiline. [DOCUMENT] TITLE: StrictDoc [REQUIREMENT] UID: REQ-001 STATEMENT: StrictDoc shall enable requirements management. COMMENT: Clarify the meaning or give additional information here. RATIONALE: The presence of the REQ-001 is justified. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Section | 4.2.3 |
Section
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Free text | – |
The [SECTION] element is used for creating document chapters and grouping requirements into logical groups. It is equivalent to the use of #, ##, ###, etc., in Markdown and ====, ----, ~~~~ in RST. [DOCUMENT] TITLE: StrictDoc [SECTION] TITLE: High-level requirements [REQUIREMENT] UID: HIGH-001 STATEMENT: ... [/SECTION] [SECTION] TITLE: Implementation requirements [REQUIREMENT] UID: IMPL-001 STATEMENT: ... [/SECTION] |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Section | 4.2.3.1 |
Nesting sections
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Free text | – |
Sections can be nested within each other. [DOCUMENT] TITLE: StrictDoc [SECTION] TITLE: Chapter [SECTION] TITLE: Subchapter [REQUIREMENT] STATEMENT: ... [/SECTION] [/SECTION] StrictDoc creates section numbers automatically. In the example above, the sections will have their titles numbered accordingly: 1 Chapter and 1.1 Subchapter. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Section | 4.2.3.2 |
Free text
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Free text | – |
A section can have a block of [FREETEXT] connected to it: [DOCUMENT] TITLE: StrictDoc [SECTION] TITLE: Free text [FREETEXT] A sections can have a block of ``[FREETEXT]`` connected to it: ... [/FREETEXT] [/SECTION] According to the Strict Rule #2, arbitrary content cannot be written outside of StrictDoc's grammar structure. [SECTION] / [FREETEXT] is therefore a designated grammar element for writing free text content. Note: Free text can also be called "nonnormative" or "informative" text because it does not contribute anything to the traceability information of the document. The nonnormative text is there to give a context to the reader and help with the conceptual understanding of the information. If a certain information influences or is influenced by existing requirements, it has to be promoted to the requirement level: the information has to be broken down into atomic [REQUIREMENT] statements and get connected to the other requirement statements in the document. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Section | 4.2.3.3 |
Section without a level
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Free text | – |
A section can have no level attached to it. To enable this behavior, the field LEVEL has to be set to None. [DOCUMENT] TITLE: Hello world doc [SECTION] TITLE: Section 1 [/SECTION] [SECTION] LEVEL: None TITLE: Out-of-band Section [/SECTION] [SECTION] TITLE: Section 2 [/SECTION] The section with no level will be skipped by StrictDoc's system of automatic numbering of the section levels (1, 1.1, 1.2, 2, ...). The behavior of the LEVEL: None option is recursive. If a parent section has its LEVEL set to None, all its subsections' and requirements' levels are set to LEVEL: None by StrictDoc automatically. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Section | 4.2.4 |
Composite requirement
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Free text | – |
A [COMPOSITE_REQUIREMENT] is a requirement that combines requirement properties of a [REQUIREMENT] element and grouping features of a [SECTION] element. This element can be useful in lower-level specifications documents where a given section of a document has to describe a single feature and the description requires a one or more levels of nesting. In this case, it might be natural to use a composite requirement that is tightly connected to a few related sub-requirements. [COMPOSITE_REQUIREMENT] STATEMENT: Statement [REQUIREMENT] STATEMENT: Substatement #1 [REQUIREMENT] STATEMENT: Substatement #2 [REQUIREMENT] STATEMENT: Substatement #3 [/COMPOSITE_REQUIREMENT] Special feature of [COMPOSITE_REQUIREMENT]: like [SECTION] element, the [COMPOSITE_REQUIREMENT] elements can be nested within each other. However, [COMPOSITE_REQUIREMENT] cannot nest sections. Note: Composite requirements should not be used in every document. Most often, a more basic combination of nested [SECTION] and [REQUIREMENT] elements should do the job. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Section | 4.2.5 |
Include files
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Free text | – |
StrictDoc .sdoc files can be built-up from including other fragment documents. The [FRAGMENT_FROM_FILE] element can be used anywhere body elements can be used ( e.g.``[SECTION]``, [REQUIREMENT, [COMPOSITE_REQUIREMENT] etc.) and will evaluate by inserting its contents from the file referenced by its FILE: property where it was used in the parent document. The files included must start with a [FRAGMENT] directive and cannot contain [FREETEXT] elements but are otherwise identical to *.sdoc files. They can have any filename except a``.sdoc`` extension. Here is an example pair of files similar to examples above. First the .sdoc file has a [FRAGMENT_FROM_FILE] that references the latter file. [DOCUMENT] TITLE: StrictDoc [FREETEXT] ... [/FREETEXT] [FRAGMENT_FROM_FILE] FILE: include.ssec [REQUIREMENT] Then the referenced file, include.ssec: [FRAGMENT] [REQUIREMENT] [SECTION] TITLE: Sub section [/SECTION] [COMPOSITE_REQUIREMENT] [REQUIREMENT] [/COMPOSITE_REQUIREMENT] Which will resolve to the following document after inclusion: [DOCUMENT] TITLE: StrictDoc [FREETEXT] ... [/FREETEXT] [REQUIREMENT] [SECTION] TITLE: Sub section [/SECTION] [COMPOSITE_REQUIREMENT] [REQUIREMENT] [/COMPOSITE_REQUIREMENT] [REQUIREMENT] |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Section | 4.3 |
Custom grammars
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Free text | – |
Observation: Different industries have their own types of requirements documents with specialized meta information. Examples: ASIL in the automotive industry or HERITAGE field in some of the requirements documents by NASA. StrictDoc allows declaration of custom grammars with custom fields that are specific to a particular document. First, such fields have to be registered on a document level using the [GRAMMAR] field. The following example demonstrates a declaration of a grammar with four fields including a custom VERIFICATION field. [DOCUMENT] TITLE: How to declare a custom grammar [GRAMMAR] ELEMENTS: - TAG: REQUIREMENT FIELDS: - TITLE: UID TYPE: String REQUIRED: True - TITLE: VERIFICATION TYPE: String REQUIRED: True - TITLE: TITLE TYPE: String REQUIRED: True - TITLE: STATEMENT TYPE: String REQUIRED: True - TITLE: COMMENT TYPE: String REQUIRED: True This declaration configures the parser to recognize the declared fields as defined by a user. Declaring a special field as REQUIRED: True makes this field mandatory for each and every requirement in the document. When the fields are registered on the document level, it becomes possible to declare them as the [REQUIREMENT] special fields: [REQUIREMENT] UID: ABC-123 VERIFICATION: Test STATEMENT: System A shall do B. COMMENT: Test comment. Note: The order of fields must match the order of their declaration in the grammar. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Section | 4.3.1 |
Supported field types
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Free text | – |
The supported field types are:
Example: [DOCUMENT] TITLE: How to declare a custom grammar [GRAMMAR] ELEMENTS: - TAG: REQUIREMENT FIELDS: - TITLE: UID TYPE: String REQUIRED: True - TITLE: ASIL TYPE: SingleChoice(A, B, C, D) REQUIRED: True - TITLE: VERIFICATION TYPE: MultipleChoice(Review, Analysis, Inspection, Test) REQUIRED: True - TITLE: UNIT TYPE: Tag REQUIRED: True - TITLE: TITLE TYPE: String REQUIRED: True - TITLE: STATEMENT TYPE: String REQUIRED: True - TITLE: COMMENT TYPE: String REQUIRED: True [FREETEXT] This document is an example of a simple SDoc custom grammar. [/FREETEXT] [REQUIREMENT] UID: ABC-123 ASIL: A VERIFICATION: Review, Test UNIT: OBC, RTU TITLE: Function B STATEMENT: System A shall do B. COMMENT: Test comment. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Section | 4.3.2 |
Reserved fields
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Free text | – |
While it is possible to declare a grammar with completely custom fields, there is a fixed set of reserved fields that StrictDoc uses for the presentation of table of contents and document structure:
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Section | 5 |
Markup
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Free text | – |
The Restructured Text (reST) markup is the default markup supported by StrictDoc. The reST markup can be written inside all StrictDoc's text blocks, such as [FREETEXT], STATEMENT, COMMENT, RATIONALE. See the reST syntax documentation for a full reference. The support of Tex and HTML is planned. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Section | 5.1 |
Images
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Free text | – |
This is the example of how images are included using the reST syntax: [FREETEXT] .. image:: _assets/sandbox1.svg :alt: Sandbox demo :class: image [/FREETEXT] |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Section | 6 |
Export formats
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Section | 6.1 |
HTML documentation tree by StrictDoc
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Free text | – |
This is a default export option supported by StrictDoc. The following command creates an HTML export: strictdoc export docs/ --formats=html --output-dir output-html Example: This documentation is exported by StrictDoc to HTML: StrictDoc HTML export. Note: The options --formats=html and --output-dir output-html can be skipped because HTML export is a default export option and the default output folder is output. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Section | 6.1.1 |
Mathjax support
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Free text | – |
The option --enable-mathjax makes StrictDoc to include the Mathjax Javascript library to all of the document templates. strictdoc export docs/ --enable-mathjax --output-dir output-html Example of using Mathjax: [FREETEXT] .. raw:: latex html $$ \mathbf{\underline{k}}_{\text{a}} = \mathbf{\underline{i}}_{\text{a}} \times \mathbf{\underline{j}}_{\text{a}} $$ [/FREETEXT] |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Section | 6.1.2 |
Standalone HTML pages (experimental)
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Free text | – |
The following command creates a normal HTML export with all pages having their assets embedded into HTML using Data URI / Base64: strictdoc export docs/ --formats=html-standalone --output-dir output-html The generated document are self-contained HTML pages that can be shared via email as single files. This option might be especially useful if you work with a single document instead of a documentation tree with multiple documents. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Section | 6.2 |
HTML export via Sphinx
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Free text | – |
The following command creates an RST export: strictdoc export YourDoc.sdoc --formats=rst --output-dir output The created RST files can be copied to a project created using Sphinx, see Getting Started with Sphinx. cp -v output/YourDoc.rst docs/sphinx/source/ cd docs/sphinx && make html StrictDoc's own Sphinx/HTML documentation is generated this way, see the Invoke task: invoke sphinx. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Section | 6.3 |
PDF export via Sphinx/LaTeX
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Free text | – |
The following command creates an RST export: strictdoc export YourDoc.sdoc --formats=rst --output-dir output The created RST files can be copied to a project created using Sphinx, see Getting Started with Sphinx. cp -v output/YourDoc.rst docs/sphinx/source/ cd docs/sphinx && make pdf StrictDoc's own Sphinx/PDF documentation is generated this way, see the Invoke task: invoke sphinx. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Section | 7 |
Traceability between requirements and source code
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Free text | – |
Note: This feature is experimental, the documentation is incomplete. StrictDoc allows connecting requirements to source code files. Two types of links are supported: 1) A basic link where a requirement links to a whole file. [REQUIREMENT] UID: REQ-001 REFS: - TYPE: File VALUE: file.py TITLE: File reference STATEMENT: This requirement references the file. 2) A range-based link where a requirement links to a file and additionally in the file, there is a reverse link that connects a source range back to the requirement: The requirement declaration contains a reference of the type File: [REQUIREMENT] UID: REQ-001 REFS: - TYPE: File VALUE: file.py TITLE: Whole file reference STATEMENT: This requirement references the file.py file. COMMENT: >>> If the file.py contains a source range that is connected back to this requirement (REQ-001), the link becomes a link to the source range. <<< The source file: # [REQ-002] def hello_world(): print("hello world") # [/REQ-002] To activate the traceability to source files, use --experimental-enable-file-traceability option: strictdoc export . --experimental-enable-file-traceability --output-dir output/ Currently, StrictDoc looks for source files in a directory from which the strictdoc command is run. The tests/integration/examples folder contains executable examples including the example of requirements-to-source-code traceability. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Section | 8 |
ReqIF support
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Free text | – |
StrictDoc has an initial support of exporting to and importing from the ReqIF format. Note: It is not possible to implement a single export/import procedure that works well for all ReqIF XML files produced by various requirements management tools. The export/import workflow is therefore tool-specific. See ReqIF implementation details for more details. Supported formats:
Planned formats:
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Section | 8.1 |
Import flow (ReqIF -> SDoc):
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Free text | – |
strictdoc import reqif sdoc input.reqif output.sdoc The command does the following:
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Section | 8.2 |
Export flow (SDoc -> ReqIF)
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Free text | – |
strictdoc export --formats=reqif-sdoc %S/input.sdoc The command does the following:
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Section | 8.3 |
ReqIF implementation details
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Free text | – |
The ReqIF is a standard which is maintained by Object Management Group (OMG). One important feature of the ReqIF standard is that it requires a fixed XML structure but still leaves certain details open to the implementation by the ReqIF and requirements management tools developers. Specifically, each tool may use it own field names and structure to represent requirements and sections/chapters. In order to accommodate for the differences between ReqIF files produced by various tools, the ReqIF processing is split into two layers: 1) Parsing ReqIF from .reqif XML files into ReqIF in-memory tree of Python objects as well as unparsing the ReqIF in-memory tree back to ReqIF XML files is extracted to a separate library: strictdoc-project/reqif. 2) Converting between in-memory trees of SDoc and ReqIF. This layer is part of StrictDoc. For further overview of the ReqIF format and the reqif library's implementation details, refer to strictdoc-project/reqif's documentation. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Section | 9 |
Excel support
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Free text | – |
StrictDoc provides a support for Excel XLS on input and Excel XLSX on output. On input, the headers of sheet1 are used to put together a custom grammar and the requirements are imported one row per requirement. A best effort is made by the importer to recognize names of headers and map these to strictdoc requirement fields. Note: A roundtrip "SDoc -> Excel -> SDoc" is not yet supported. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Section | 9.1 |
Import flow (Excel XLS -> SDoc):
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Free text | – |
strictdoc import excel basic input.xls output.sdoc The command does the following:
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Section | 9.2 |
Export flow (SDoc -> Excel XLSX)
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Free text | – |
strictdoc export --formats=excel --output-dir=Output input.sdoc The command does the following:
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Section | 10 |
Options
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Section | 10.1 |
Project title
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Free text | – |
By default, StrictDoc generates a project tree with a project title "Untitled Project". To specify the project title use the option --project-title. strictdoc export --project-title "My Project" . |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Section | 10.2 |
Parallelization
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Free text | – |
To improve performance for the large document trees (1000+ requirements), StrictDoc parallelizes reading and generation of the documents using process-based parallelization: multiprocessing.Pool and multiprocessing.Queue. Parallelization improves performance but can also complicate understanding behavior of the code if something goes wrong. To disable parallelization use the --no-parallelization option: strictdoc export --no-parallelization docs/ Note: Currently, only the generation of HTML documents is parallelized, so this option will only have effect on the HTML export. All other export options are run from the main thread. Reading of the SDoc documents is parallelized for all export options and is disabled with this option as well. |