diff --git a/docs/strictdoc_01_user_guide.sdoc b/docs/strictdoc_01_user_guide.sdoc index 49cd3a822..4b7dadca7 100644 --- a/docs/strictdoc_01_user_guide.sdoc +++ b/docs/strictdoc_01_user_guide.sdoc @@ -8,7 +8,8 @@ OPTIONS: [SECTION] TITLE: Introduction -[FREETEXT] +[TEXT] +STATEMENT: >>> StrictDoc is software for technical documentation and requirements management. Summary of StrictDoc features: @@ -42,17 +43,18 @@ Summary of StrictDoc features: Further performance tuning should be possible. See also a summary of StrictDoc's existing limitations: [LINK: SDOC_UG_LIMIT]. -[/FREETEXT] +<<< [SECTION] UID: SDOC_UG_CONTACT TITLE: Contact the developers -[FREETEXT] +[TEXT] +STATEMENT: >>> Join us in Discord. Here is the invitation link: https://discord.gg/4BAAME9MmG The author can be also contacted via `email `_. -[/FREETEXT] +<<< [/SECTION] @@ -65,7 +67,8 @@ TITLE: Examples UID: SDOC_UG_HELLO_WORLD TITLE: Hello World -[FREETEXT] +[TEXT] +STATEMENT: >>> "Hello World" example of the SDoc text language: .. code-block:: text @@ -125,32 +128,35 @@ The expected output should contain the following line: INFO: Uvicorn running on http://127.0.0.1:5111 (Press CTRL+C to quit) Open the URL in the browser and explore the contents of the example. -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: StrictDoc Examples repository -[FREETEXT] +[TEXT] +STATEMENT: >>> The `strictdoc-examples `_ repository contains a collection of basic examples. Visit the repository and read its README for details. -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: StrictDoc Templates repository -[FREETEXT] +[TEXT] +STATEMENT: >>> The `strictdoc-templates `_ repository contains a growing collection of templates from the industry standards like DO-178C (aviation) and ECSS-E-ST-40C (space). -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: Other examples -[FREETEXT] +[TEXT] +STATEMENT: >>> For a more comprehensive example, check the source file of this documentation which is written using StrictDoc: `strictdoc_01_user_guide.sdoc `_. @@ -158,7 +164,7 @@ which is written using StrictDoc: - `StrictDoc HTML export `_ - `StrictDoc HTML export using Sphinx `_ - `StrictDoc PDF export using Sphinx `_ -[/FREETEXT] +<<< [/SECTION] @@ -171,7 +177,8 @@ TITLE: Installing StrictDoc [SECTION] TITLE: Requirements -[FREETEXT] +[TEXT] +STATEMENT: >>> - Python 3.8+ - macOS, Linux or Windows - Command-line terminal program @@ -183,38 +190,41 @@ Depending on an operating system, a terminal program can be, for example: - ``Terminal`` or ``PowerShell`` on Windows. A terminal program is required to input all the commands outlined in this user guide. -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: Installing StrictDoc as a Pip package (recommended way) -[FREETEXT] +[TEXT] +STATEMENT: >>> .. code-block:: text pip install strictdoc -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: Installing "nightly" StrictDoc as a Pip package -[FREETEXT] +[TEXT] +STATEMENT: >>> Sometimes, it takes a while before the latest features and fixes reach the stable Pip release. In that case, installing a Pip package from the Git repository directly is possible: .. code-block:: pip install -U --pre git+https://github.com/strictdoc-project/strictdoc.git@main -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: Installing StrictDoc into a Docker container -[FREETEXT] +[TEXT] +STATEMENT: >>> 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. @@ -234,17 +244,18 @@ In the container terminal: bash-5.1# exit The documentation resides in ``./docs/output/html``. -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: Installing StrictDoc as a Snap package (not maintained) -[FREETEXT] +[TEXT] +STATEMENT: >>> 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``. -[/FREETEXT] +<<< [/SECTION] @@ -256,7 +267,8 @@ TITLE: Running StrictDoc [SECTION] TITLE: Static HTML export -[FREETEXT] +[TEXT] +STATEMENT: >>> The easiest way to see the static HTML export feature in action is to run the [LINK: SDOC_UG_HELLO_WORLD] example. The ``export`` command is the main producer of documentation. The native export format of StrictDoc is HTML. The ``export`` command supports a number of parameters, including the option for selecting export formats (HTML, RST, Excel, etc.). The options can be explored with the ``--help`` command. @@ -264,14 +276,15 @@ The ``export`` command is the main producer of documentation. The native export .. code-block:: bash strictdoc export --help -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: Web server -[FREETEXT] +[TEXT] +STATEMENT: >>> StrictDoc supports a web-based user interface. The StrictDoc web server is launched via the ``server`` command which accepts a path to a documentation tree as a parameter. .. code-block:: bash @@ -285,14 +298,15 @@ The ``server`` command accepts a number of options. To explore the options, run: strictdoc server --help **Note:** The implementation of the web interface is work-in-progress. See [LINK: SDOC_UG_LIMIT_WEB] for an overview of the existing limitations. -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: Security considerations -[FREETEXT] +[TEXT] +STATEMENT: >>> .. warning:: **TL;DR**: StrictDoc's web server is not yet hardened against unsafe use. Making StrictDoc safe for deployment in public networks is an ongoing effort. @@ -311,7 +325,7 @@ What makes StrictDoc's web server unsafe: Known security-related issues are tracked on GitHub, under the `"Security" label `_. As StrictDoc becomes usable without command-line access, all known issues will need to be addressed or acknowledged as known limitations. We are committed to continuously enhancing the functionality and security of StrictDoc and welcome user feedback and contributions in this area. -[/FREETEXT] +<<< [/SECTION] @@ -321,7 +335,8 @@ We are committed to continuously enhancing the functionality and security of Str UID: SDOC_UG_IDE_SUPPORT TITLE: IDE support -[FREETEXT] +[TEXT] +STATEMENT: >>> StrictDoc language markup (SDoc) can be activated in all IDEs that support the TextMate grammars. When the StrictDoc grammar is integrated into an IDE, the SDoc syntax becomes highlighted just as any other syntax like Markdown, RST, @@ -358,14 +373,15 @@ can be only achieved with a dedicated Language Server Protocol (LSP) implementation for StrictDoc. The StrictDoc LSP is on StrictDoc's long-term roadmap, see `Enhancement: Language Protocol Server for SDoc text language #577 `_. -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: SDoc syntax -[FREETEXT] +[TEXT] +STATEMENT: >>> StrictDoc defines a special syntax for writing specifications documents. This syntax is called SDoc and it's grammar is encoded with the `textX `_ @@ -384,7 +400,7 @@ This is how a minimal possible SDoc document looks like: This documentation is written using StrictDoc. Here is the source file: `strictdoc_01_user_guide.sdoc `_. -[/FREETEXT] +<<< [SECTION] TITLE: Document structure @@ -404,12 +420,13 @@ Each construct is described in more detail below. UID: SECTION-UG-Strict-rule-1 TITLE: Strict rule #1: One empty line between all nodes -[FREETEXT] +[TEXT] +STATEMENT: >>> 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. -[/FREETEXT] +<<< [/SECTION] @@ -432,7 +449,8 @@ be specified using ``[TEXT]`` nodes. UID: SECTION-UG-Strict-rule-3 TITLE: Strict rule #3: No empty strings -[FREETEXT] +[TEXT] +STATEMENT: >>> StrictDoc's grammar does not allow empty strings. This rule is applicable to both single-line and multiline strings and both section fields and requirement fields. A field is either missing or is a non-empty string. @@ -470,7 +488,7 @@ If you need to provide a placeholder for a field that you know has to be filled out soon, add a "TBD" (to be done, by our team) or a "TBC" (to be confirmed with a customer or a supplier) string. The Project Statistics screen provides metrics for counting the number of TBDs (To Be Determined) and TBCs (To Be Confirmed) in a document, assisting in evaluating the document's maturity. This is a common practice in the regulared industries. See [LINK: SECTION-UG-Project-statistics-screen] for more details. -[/FREETEXT] +<<< [/SECTION] @@ -534,7 +552,8 @@ by the document's Grammar, i.e. should not be changed. UID: DOCUMENT_FIELD_OPTIONS TITLE: Document configuration options -[FREETEXT] +[TEXT] +STATEMENT: >>> The ``OPTIONS`` field may have the following attribute fields: .. list-table:: SDoc grammar ``DOCUMENT``-``OPTIONS`` fields @@ -558,32 +577,35 @@ The ``OPTIONS`` field may have the following attribute fields: * - ``REQUIREMENT_IN_TOC`` - ``True`` (default), ``False`` -[/FREETEXT] +<<< [SECTION] TITLE: ENABLE_MID -[FREETEXT] +[TEXT] +STATEMENT: >>> See [LINK: SECTION-UG-Machine-identifiers-MID]. -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: MARKUP -[FREETEXT] +[TEXT] +STATEMENT: >>> The ``MARKUP`` option controls which markup renderer will be used. The available options are: ``RST``, ``HTML`` and ``Text``. Default is ``RST``. -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: AUTO_LEVELS -[FREETEXT] +[TEXT] +STATEMENT: >>> The ``AUTO_LEVELS`` option controls StrictDoc's system of automatic numbering of the section levels. The available options are: ``On`` / ``Off``. Default is ``On``. @@ -593,14 +615,15 @@ contain ``None`` to exclude that section from StrictDoc's automatic section numbering. See also [LINK: SECTION_WITHOUT_A_LEVEL]. In case of ``Off``, all ``[SECTION].LEVEL`` fields must be populated. -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: REQUIREMENT_STYLE -[FREETEXT] +[TEXT] +STATEMENT: >>> The ``REQUIREMENT_STYLE`` option controls whether requirement's elements are displayed inline or as table blocks. The available options are: @@ -616,14 +639,15 @@ Default is ``Inline``. TITLE: Hello world OPTIONS: REQUIREMENT_STYLE: Inline -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: REQUIREMENT_IN_TOC -[FREETEXT] +[TEXT] +STATEMENT: >>> The ``REQUIREMENT_IN_TOC`` option controls whether requirement's title appear in the table of contents (TOC). The available options are: ``True`` / ``False``. Default is ``True``. @@ -634,7 +658,7 @@ Default is ``True``. TITLE: Hello world OPTIONS: REQUIREMENT_IN_TOC: True -[/FREETEXT] +<<< [/SECTION] @@ -729,7 +753,8 @@ present. [SECTION] TITLE: UID -[FREETEXT] +[TEXT] +STATEMENT: >>> Unique identifier of the requirement. **Observation:** Some documents do not use unique identifiers which makes it @@ -754,38 +779,41 @@ typical conventions for naming UIDs: [REQUIREMENT] UID: SDOC-HIGH-DATA-MODEL STATEMENT: STATEMENT: StrictDoc shall be based on a well-defined data model. -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: Level -[FREETEXT] +[TEXT] +STATEMENT: >>> Also a ``[REQUIREMENT]`` can have no section level attached to it. To enable this behavior, the field ``LEVEL`` has to be set to ``None``. -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: Status -[FREETEXT] +[TEXT] +STATEMENT: >>> Defines the current status of the ``[REQUIREMENT]``, e.g. ``Draft``, ``Active``, ``Deleted``. -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: Tags -[FREETEXT] +[TEXT] +STATEMENT: >>> Allows to add tags to a ``[REQUIREMENT]``. Tags are a comma separated list of single words. Only Alphanumeric tags (a-z, A-Z, 0-9 and underscore) are supported. -[/FREETEXT] +<<< [/SECTION] @@ -793,7 +821,8 @@ supported. UID: SDOC_UG_REQUIREMENT_RELATIONS TITLE: Relations (previously REFS) -[FREETEXT] +[TEXT] +STATEMENT: >>> The ``RELATIONS`` field is used to connect requirements to each other: .. code-block:: text @@ -838,12 +867,13 @@ etc.) is planned. **Note:** By design, StrictDoc will only show parent or child links if both requirements connected with a reference have ``UID`` defined. -[/FREETEXT] +<<< [SECTION] TITLE: Requirement relation roles -[FREETEXT] +[TEXT] +STATEMENT: >>> A requirement relation can be specialized with a role. The role must be registered in the document grammar, see [LINK: SDOC_UG_GRAMMAR_RELATIONS]. .. code-block:: @@ -872,7 +902,7 @@ A requirement relation can be specialized with a role. The role must be register ROLE: Refines In this example REQ-1 is the parent of REQ-2 and REQ-2 refines REQ-1. -[/FREETEXT] +<<< [/SECTION] @@ -881,7 +911,8 @@ In this example REQ-1 is the parent of REQ-2 and REQ-2 refines REQ-1. [SECTION] TITLE: Title -[FREETEXT] +[TEXT] +STATEMENT: >>> The title of the requirement. Every requirement should have its ``TITLE`` field specified. @@ -897,24 +928,26 @@ titles but some documents only use statements without title in which case their [REQUIREMENT] UID: REQ-001 STATEMENT: StrictDoc shall enable requirements management. -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: Statement -[FREETEXT] +[TEXT] +STATEMENT: >>> The statement of the requirement. The field can be single-line or multiline. Every requirement shall have its ``STATEMENT`` field specified. -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: Rationale -[FREETEXT] +[TEXT] +STATEMENT: >>> A requirement should have a ``RATIONALE`` field that explains/justifies why the requirement exists. Like comments, the rationale field can be single-line or multiline. @@ -929,14 +962,15 @@ or multiline. STATEMENT: StrictDoc shall enable requirements management. COMMENT: Clarify the meaning or give additional information here. RATIONALE: The presence of the REQ-001 is justified. -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: Comment -[FREETEXT] +[TEXT] +STATEMENT: >>> A requirement can have one or more comments explaining the requirement. The comments can be single-line or multiline. @@ -956,7 +990,7 @@ comments can be single-line or multiline. Each line is rendered as a separate paragraph. <<< -[/FREETEXT] +<<< [/SECTION] @@ -966,7 +1000,8 @@ comments can be single-line or multiline. UID: ELEMENT_SECTION TITLE: Section -[FREETEXT] +[TEXT] +STATEMENT: >>> 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. @@ -993,12 +1028,13 @@ requirements into logical groups. It is equivalent to the use of ``#``, ``##``, STATEMENT: ... [/SECTION] -[/FREETEXT] +<<< [SECTION] TITLE: Nesting sections -[FREETEXT] +[TEXT] +STATEMENT: >>> Sections can be nested within each other. .. code-block:: text @@ -1022,7 +1058,7 @@ Sections can be nested within each other. StrictDoc creates section numbers automatically. In the example above, the sections will have their titles numbered accordingly: ``1 Chapter`` and ``1.1 Subchapter``. -[/FREETEXT] +<<< [/SECTION] @@ -1030,7 +1066,8 @@ sections will have their titles numbered accordingly: ``1 Chapter`` and UID: SECTION_WITHOUT_A_LEVEL TITLE: Section without a level -[FREETEXT] +[TEXT] +STATEMENT: >>> A section can have no level attached to it. To enable this behavior, the field ``LEVEL`` has to be set to ``None``. @@ -1061,7 +1098,7 @@ 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. -[/FREETEXT] +<<< [/SECTION] @@ -1153,7 +1190,8 @@ Which will resolve to the following document after inclusion: UID: UG_COMPOSITE_REQUIREMENT TITLE: Composite requirement -[FREETEXT] +[TEXT] +STATEMENT: >>> .. note:: The composite requirements feature shows promise, but it has not yet attracted significant demand from both the core developers of StrictDoc and its users. While the use of composite requirements via the command line is implemented and supported, the web interface does not currently offer this support. Experience has shown that composite requirements can often be represented as a combination of sections and standard requirements. If there is a compelling use case for full support of composite requirements, please reach out to the developers. @@ -1188,7 +1226,7 @@ Special feature of ``[COMPOSITE_REQUIREMENT]``: like ``[SECTION]`` element, the **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. -[/FREETEXT] +<<< [/SECTION] @@ -1198,7 +1236,8 @@ elements should do the job. UID: SECTION-UG-Machine-identifiers-MID TITLE: Machine identifiers (MID) -[FREETEXT] +[TEXT] +STATEMENT: >>> StrictDoc supports the automatic generation of machine identifiers (MIDs). This optional feature can be enabled individually for each document through the document-level ``ENABLE_MID`` config option: .. code-block:: @@ -1232,7 +1271,7 @@ Advantages of using machine identifiers: 3. MIDs increase the portability of requirements data. Even when UID naming conventions change or nodes are relocated, the MID continues to uniquely identify the original node. For larger projects, particularly those with extended maintenance cycles, we strongly recommend activating machine identifiers early in the project lifecycle. This proactive approach ensures robust tracking and management of documentation throughout the project's duration. -[/FREETEXT] +<<< [/SECTION] @@ -1415,7 +1454,8 @@ Example: [SECTION] TITLE: Reserved fields -[FREETEXT] +[TEXT] +STATEMENT: >>> 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 the table of contents and the document structure: @@ -1448,7 +1488,7 @@ is a fixed set of reserved fields that StrictDoc uses for the presentation of th * - RATIONALE - The rationale for a requirement. Visually presented in the same way as a comment. -[/FREETEXT] +<<< [/SECTION] @@ -1456,7 +1496,8 @@ is a fixed set of reserved fields that StrictDoc uses for the presentation of th UID: SDOC_UG_GRAMMAR_RELATIONS TITLE: Relations -[FREETEXT] +[TEXT] +STATEMENT: >>> The custom grammar configuration includes the optional ``RELATION:`` section which specifies the relations a given document supports. .. code-block:: @@ -1485,12 +1526,13 @@ The custom grammar configuration includes the optional ``RELATION:`` section whi The supported relation types are ``Parent``, ``Child``, ``File``. The Parent/Child relations are valid between requirements, the File relation connects a requirement with a file. The default grammar relations, when a custom grammar is not specified, are ``Parent`` and ``File``. -[/FREETEXT] +<<< [SECTION] TITLE: Relation roles -[FREETEXT] +[TEXT] +STATEMENT: >>> StrictDoc's custom grammar support the configuration of relation roles. The Parent and Child relations can be further specialized with roles, such as Refines, Implements, Verifies, etc. .. code-block:: @@ -1508,7 +1550,7 @@ StrictDoc's custom grammar support the configuration of relation roles. The Pare ROLE: Refines With this grammar, StrictDoc will only allow creating requirements that have Parent relations with the ``ROLE: Refines`` specified. Any other relations will trigger validation errors. -[/FREETEXT] +<<< [/SECTION] @@ -1516,7 +1558,8 @@ With this grammar, StrictDoc will only allow creating requirements that have Par UID: SDOC_UG_GRAMMAR_RELATIONS_PARENT_VS_CHILD TITLE: Parent vs Child relations -[FREETEXT] +[TEXT] +STATEMENT: >>> **TL;DR** If there is no compelling reason to use the Child relations, avoid using them. Most of the technical requirements documents can be modeled with just a Parent relation type. A typical traceability graph for a requirements project is typically child-to-parent, where the higher-level parent requirements are referred to as "Parents" by their child requirements. @@ -1576,7 +1619,7 @@ With such a setup, StrictDoc generates the correct traceability graph that will Another example can be adapting the requirements of the Off-the-Shelf (OTS) project to the higher-level requirements of the user project. An intermediate requirements document can be created that connects the parent requirements of the user project with the immutable child requirements of the OTS project. This intermediate document can link the user requirement with the Parent and the OTS project with a Child link. Both examples above involve activity called Tailoring when an intermediate document (Compliance Matrix) serves as an interface between two layers of documents. -[/FREETEXT] +<<< [/SECTION] @@ -1585,7 +1628,8 @@ Both examples above involve activity called Tailoring when an intermediate docum [SECTION] TITLE: Importing grammar from grammar file -[FREETEXT] +[TEXT] +STATEMENT: >>> A document grammar can be described in a separate file with an extension ``.sgra`` and imported to a document. This feature may be useful when multiple documents need to share the same grammar. Example: @@ -1624,7 +1668,7 @@ When a ``[GRAMMAR]`` is declared with an ``IMPORT_FROM_FILE`` line, the grammar .. note:: Editing of the grammars defined in ``.sgra`` files can be only done with a text editor, it is not implemented yet in the editable web interface. -[/FREETEXT] +<<< [/SECTION] @@ -1634,14 +1678,16 @@ When a ``[GRAMMAR]`` is declared with an ``IMPORT_FROM_FILE`` line, the grammar UID: SDOC_UG_LINKS_AND_ANCHORS TITLE: Links -[FREETEXT] +[TEXT] +STATEMENT: >>> StrictDoc supports creating inline links to document sections, anchors, requirements and custom grammar elements. -[/FREETEXT] +<<< [SECTION] TITLE: Links -[FREETEXT] +[TEXT] +STATEMENT: >>> Elements that have an UID can be referenced from section text using a ``[LINK: ]`` tag. To reference a section that has an UID, use ``[LINK:
]`` tag. Likewise, a requirement can be referenced with ``[LINK: ]``. @@ -1651,14 +1697,15 @@ Example: The following link references a section: [LINK: SDOC_UG_LINKS_AND_ANCHORS]. **Note:** Adding a ``LINK`` tag will only work from the section text. In the requirement fields, the LINK tag will not be recognized. -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: Anchors -[FREETEXT] +[TEXT] +STATEMENT: >>> The ``[ANCHOR: , ]`` tag creates an anchor that can be referenced from other pages using ``[LINK ]``. Example: @@ -1666,16 +1713,17 @@ Example: This is a link to anchor: [LINK: ANCHOR-EXAMPLE]. Note: ``ANCHOR`` is a block-level tag. It has to be placed in the beginning of a line with a newline break after the tag. -[/FREETEXT] +<<< [SECTION] TITLE: Anchor example -[FREETEXT] +[TEXT] +STATEMENT: >>> This section contains an anchor named ``Anchor ABC``. [ANCHOR: ANCHOR-EXAMPLE, Anchor ABC] -[/FREETEXT] +<<< [/SECTION] @@ -1688,16 +1736,18 @@ This section contains an anchor named ``Anchor ABC``. [SECTION] TITLE: Search and filtering -[FREETEXT] +[TEXT] +STATEMENT: >>> StrictDoc supports the search and filtering of document content. The web interface includes the Search screen, designed for conducting queries against a document tree. The command-line interface supports filtering of requirements and sections through the ``export`` commands. -[/FREETEXT] +<<< [SECTION] TITLE: Query engine -[FREETEXT] +[TEXT] +STATEMENT: >>> The syntax of the search query is inspired by Python, utilizing a fixed grammar that converts search queries into corresponding Python expressions. Important rules: @@ -1730,14 +1780,15 @@ Important rules: * - ``(node.is_requirement and node.has_child_requirements)`` - Find all requirements which have child requirements. -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: Filtering content -[FREETEXT] +[TEXT] +STATEMENT: >>> Both ``export`` command-line interface commands support filtering documentation content with ``--filter-requirements`` and ``--filter-sections`` options. Both options are based on the Query Engine, so the same rules that are valid for Search also apply for filtering. When a filter is applied, only the whitelisted requirements/sections will be exported. @@ -1747,7 +1798,7 @@ Example: .. code-block:: strictdoc export . --filter-requirements '"System" in node["TITLE"]' -[/FREETEXT] +<<< [/SECTION] @@ -1838,7 +1889,8 @@ TITLE: Export formats [SECTION] TITLE: HTML documentation tree by StrictDoc -[FREETEXT] +[TEXT] +STATEMENT: >>> This is a default export option supported by StrictDoc. The following command creates an HTML export: @@ -1853,12 +1905,13 @@ The following command creates an HTML export: 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``. StrictDoc does not detect .sdoc files in the output folder. This is based on the assumption that StrictDoc should not read anything in the output folder, which is intended for transient output artifacts. -[/FREETEXT] +<<< [SECTION] TITLE: Standalone HTML pages -[FREETEXT] +[TEXT] +STATEMENT: >>> The following command creates a normal HTML export with all pages having their assets embedded into HTML using Data URI / Base64. In the project's ``strictdoc.toml`` file, specify: @@ -1873,7 +1926,7 @@ assets embedded into HTML using Data URI / Base64. In the project's ``strictdoc. 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. -[/FREETEXT] +<<< [/SECTION] @@ -1882,7 +1935,8 @@ a single document instead of a documentation tree with multiple documents. [SECTION] TITLE: HTML export via Sphinx -[FREETEXT] +[TEXT] +STATEMENT: >>> The following command creates an RST export: .. code-block:: text @@ -1901,14 +1955,15 @@ The created RST files can be copied to a project created using Sphinx, see `_ is generated this way, see the Invoke task: `invoke sphinx `_. -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: PDF export via Sphinx/LaTeX -[FREETEXT] +[TEXT] +STATEMENT: >>> The following command creates an RST export: @@ -1928,14 +1983,15 @@ The created RST files can be copied to a project created using Sphinx, see `_ is generated this way, see the Invoke task: `invoke sphinx `_. -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: JSON -[FREETEXT] +[TEXT] +STATEMENT: >>> The following command creates a JSON export: .. code-block:: @@ -1945,7 +2001,7 @@ The following command creates a JSON export: The structure of the exported JSON mostly mirrors the structure of the underlying SDoc objects that represent the project tree, documents, sections, requirements, and other nodes. When the exported documents are included to other documents using the [LINK: UG_COMPOSABLE_DOCUMENTS] feature, the JSON export does not include the included documents but only the including documents with the included content. This can be changed by adding the ``--included-documents`` option. -[/FREETEXT] +<<< [/SECTION] @@ -1958,7 +2014,8 @@ TITLE: Manage project tree UID: SECTION-UG-Automatic-assignment-of-requirements-UID TITLE: Automatic assignment of requirements UID -[FREETEXT] +[TEXT] +STATEMENT: >>> To assign requirement UIDs automatically: .. code-block:: @@ -1986,7 +2043,7 @@ A section-level requirement mask: [SECTION] TITLE: Section 2. REQ_PREFIX: LEVEL2-REQ- -[/FREETEXT] +<<< [/SECTION] @@ -1996,7 +2053,8 @@ A section-level requirement mask: UID: SECTION-TRACEABILITY-REQS-TO-SOURCE-CODE TITLE: Traceability between requirements and source code -[FREETEXT] +[TEXT] +STATEMENT: >>> **Note:** This feature is experimental, the documentation is incomplete. StrictDoc allows connecting requirements to source code files. Two types of @@ -2061,14 +2119,15 @@ The `strictdoc-examples `_ repository contains executable examples including the example of requirements-to-source-code traceability. -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: ReqIF support -[FREETEXT] +[TEXT] +STATEMENT: >>> StrictDoc has an initial support of exporting to and importing from the ReqIF format. @@ -2087,12 +2146,13 @@ Planned formats: `ReqIF Implementation Guide `_ that attempts to harmonize the developments of ReqIF by requirements management tools. -[/FREETEXT] +<<< [SECTION] TITLE: Import flow (ReqIF -> SDoc) -[FREETEXT] +[TEXT] +STATEMENT: >>> .. code-block:: text strictdoc import reqif sdoc input.reqif output.sdoc @@ -2107,14 +2167,15 @@ The command does the following: used. 3. The SDoc in-memory model is written to an .sdoc file. -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: Export flow (SDoc -> ReqIF) -[FREETEXT] +[TEXT] +STATEMENT: >>> .. code-block:: text strictdoc export --formats=reqif-sdoc %S/input.sdoc @@ -2127,7 +2188,7 @@ The command does the following: argument. 3. The ReqIF in-memory model is unparsed a to ReqIF XML file using ``reqif`` library. -[/FREETEXT] +<<< [/SECTION] @@ -2135,7 +2196,8 @@ The command does the following: UID: SECTION-UG-ReqIF-options TITLE: ReqIF options -[FREETEXT] +[TEXT] +STATEMENT: >>> The following options are available for ReqIF export/import commands. ``--reqif-multiline-is-xhtml`` This option makes StrictDoc to export all multiline fields as XHTML attributes, not as STRING (the default behavior). This is useful for interfacing with tools, such as Polarion, which assume XHTML as the primary format for writing multiline text. @@ -2154,7 +2216,7 @@ All options can be also specified in a project's TOML file as follows: multiline_is_xhtml = true import_markup = "HTML" enable_mid = true -[/FREETEXT] +<<< [/SECTION] @@ -2162,7 +2224,8 @@ All options can be also specified in a project's TOML file as follows: UID: SECTION-REQIF-DETAILS TITLE: ReqIF implementation details -[FREETEXT] +[TEXT] +STATEMENT: >>> 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 @@ -2185,7 +2248,7 @@ For further overview of the ReqIF format and the ``reqif`` library's implementation details, refer to `strictdoc-project/reqif `_'s documentation. -[/FREETEXT] +<<< [/SECTION] @@ -2194,7 +2257,8 @@ documentation. [SECTION] TITLE: Excel support -[FREETEXT] +[TEXT] +STATEMENT: >>> 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 @@ -2203,12 +2267,13 @@ the importer to recognize names of headers and map these to strictdoc requirement fields. Note: A roundtrip "SDoc -> Excel -> SDoc" is not yet supported. -[/FREETEXT] +<<< [SECTION] TITLE: Import flow (Excel XLS -> SDoc) -[FREETEXT] +[TEXT] +STATEMENT: >>> .. code-block:: text strictdoc import excel basic input.xls output.sdoc @@ -2219,14 +2284,15 @@ The command does the following: library. 2. The SDoc in-memory model is written to an .sdoc file. -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: Export flow (SDoc -> Excel XLSX) -[FREETEXT] +[TEXT] +STATEMENT: >>> .. code-block:: text strictdoc export --formats=excel --output-dir=Output input.sdoc @@ -2251,7 +2317,7 @@ For exporting a folder with multiple SDoc files, specify a path to a folder or ` strictdoc export --formats=excel . If the ``output-dir`` option is not provided, the ``output/`` folder is the default value. -[/FREETEXT] +<<< [/SECTION] @@ -2264,30 +2330,33 @@ TITLE: Options UID: SDOC_UG_OPTIONS_PROJECT_LEVEL TITLE: Project-level options -[FREETEXT] +[TEXT] +STATEMENT: >>> StrictDoc supports reading configuration from a TOML file. The file must be called ``strictdoc.toml`` and shall be stored in the same folder which is provided as a path to the SDoc documents. For example, ``strictdoc export .`` will make StrictDoc recognize the config file, if it is stored under the current directory. -[/FREETEXT] +<<< [SECTION] TITLE: Project title -[FREETEXT] +[TEXT] +STATEMENT: >>> This option specifies a project title. .. code-block:: [project] title = "StrictDoc Documentation" -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: Path to assets -[FREETEXT] +[TEXT] +STATEMENT: >>> By default, StrictDoc copies its CSS/JS and other asset files to a folder ``_static`` in the HTML output directory. Sometimes, it is desirable to change the folder name. For example, the GitHub Pages static website engine expects the assets to be found in the ``assets`` folder. @@ -2298,14 +2367,15 @@ The ``html_assets_strictdoc_dir`` allows changing the assets folder name: [project] html_assets_strictdoc_dir = "assets" -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: Path to source root -[FREETEXT] +[TEXT] +STATEMENT: >>> When the ``REQUIREMENT_TO_SOURCE_TRACEABILITY`` feature is activated, StrictDoc looks for source files in the directory from which the ``strictdoc`` program is run. This can be changed with the ``source_root_path`` option. .. code-block:: @@ -2319,14 +2389,15 @@ When the ``REQUIREMENT_TO_SOURCE_TRACEABILITY`` feature is activated, StrictDoc source_root_path = "source_root/" The ``source_root_path`` option supports relative paths, e.g. ``../source_root/``. -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: Include/exclude document paths -[FREETEXT] +[TEXT] +STATEMENT: >>> Use ``include_doc_paths`` and ``exclude_doc_paths`` paths to whitelist/blacklist paths to SDoc documents. In the following example, StrictDoc will look for all files in the input project directory, except all documents in the ``tests/`` folder. @@ -2363,14 +2434,15 @@ The behavior of wildcard symbols ``*`` and ``**`` is as follows: - Match all documents found in the ``docs/`` folder and all its subdirectories. * - ``**/docs/**`` - Match all documents found in the ``docs/`` folder and all its subdirectories. The ``docs/`` folder can be a top-level folder or at any level of depth. -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: Include/exclude source files paths -[FREETEXT] +[TEXT] +STATEMENT: >>> Use ``include_source_paths`` and ``exclude_source_paths`` to whitelist/blacklist paths to source files when the traceability between requirements and source files feature is enabled. .. code-block:: yaml @@ -2390,7 +2462,7 @@ Use ``include_source_paths`` and ``exclude_source_paths`` to whitelist/blacklist ] The behavior of the wildcards is the same as for the ``include_doc_paths/exclude_doc_paths`` options. -[/FREETEXT] +<<< [/SECTION] @@ -2398,7 +2470,8 @@ The behavior of the wildcards is the same as for the ``include_doc_paths/exclude UID: SDOC_UG_CONFIG_FEATURES TITLE: Selecting features -[FREETEXT] +[TEXT] +STATEMENT: >>> StrictDoc has optional features and features that are developed with a lower priority. The feature of exporting the SDoc documents to HTML document view is a core feature and is always enabled. The option ``features`` allows selecting which additional features should be activated or not. @@ -2429,12 +2502,13 @@ The following is an example of the default configuration. The same features are ] See [LINK: SDOC_UG_EXPERIMENTAL_FEATURES] where the experimental features are outlined. -[/FREETEXT] +<<< [SECTION] TITLE: Enable all features -[FREETEXT] +[TEXT] +STATEMENT: >>> To select all available features, stable and experimental, specify ``ALL_FEATURES``. .. code-block:: @@ -2450,14 +2524,15 @@ The advantage of this option is that all feature toggles become activated, and a The disadvantage is that StrictDoc spends more time rendering extra screens that might not be needed by a particular user. If ``ALL_FEATURES`` is present, all features are activated, regardless of any other features that are also specified or not. -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: Disable all features -[FREETEXT] +[TEXT] +STATEMENT: >>> To disable all features, specify the ``features`` option but leave it empty: .. code-block:: yaml @@ -2467,7 +2542,7 @@ To disable all features, specify the ``features`` option but leave it empty: features = [ # Nothing specified. ] -[/FREETEXT] +<<< [/SECTION] @@ -2479,7 +2554,8 @@ TITLE: Server configuration [SECTION] TITLE: Host and port -[FREETEXT] +[TEXT] +STATEMENT: >>> By default, StrictDoc runs the server on ``127.0.0.1:5111``. Use the ``[server]`` section to configure the host and port as follows. @@ -2492,7 +2568,7 @@ Use the ``[server]`` section to configure the host and port as follows. [server] host = "localhost" port = 5000 -[/FREETEXT] +<<< [/SECTION] @@ -2506,7 +2582,8 @@ TITLE: Command-line interface options [SECTION] TITLE: Project title -[FREETEXT] +[TEXT] +STATEMENT: >>> By default, StrictDoc generates a project tree with a project title "Untitled Project". To specify the project title use the option ``--project-title``. @@ -2514,14 +2591,15 @@ By default, StrictDoc generates a project tree with a project title .. code-block:: text strictdoc export --project-title "My Project" . -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: Parallelization -[FREETEXT] +[TEXT] +STATEMENT: >>> 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 @@ -2540,7 +2618,7 @@ To disable parallelization use the ``--no-parallelization`` option: 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. -[/FREETEXT] +<<< [/SECTION] @@ -2551,7 +2629,8 @@ all export options and is disabled with this option as well. [SECTION] TITLE: Python API -[FREETEXT] +[TEXT] +STATEMENT: >>> At present, StrictDoc lacks a documented public Python API. Nevertheless, users can leverage StrictDoc's internal API to enhance existing functions or create custom import, export, and analysis tools. The architecture of StrictDoc is highly modular, so for each functional block there shall always be a dedicated Python class with a public interface, see [LINK: SECTION-DD-High-level-architecture]. One good example is the ``SDWriter`` class, which exercises the complete export of the Python data objects to the SDoc format. Since, the SDoc format is the primary data format of StrictDoc, the SDWriter is quite feature-rich in what it does and covers. The ``RSTWriter`` is less powerful because it does not reflect the full data model, but is probably worth a look as well. @@ -2565,7 +2644,7 @@ The ``ManageAutoUIDCommand`` class features a good use of all APIs that one may - And finally the final sequence writes the mutated traceability graph back to files using ``SDWriter``. For any custom Python API request, for example, a need to do a more advanced data analysis on SDoc data, open a GitHub issue and your specific issue will be handled. -[/FREETEXT] +<<< [/SECTION] @@ -2573,7 +2652,8 @@ For any custom Python API request, for example, a need to do a more advanced dat UID: UG_PORTABILITY_CONSIDERATIONS TITLE: Portability considerations -[FREETEXT] +[TEXT] +STATEMENT: >>> .. note:: **TL;DR**: The following topic of portability becomes relevant if documentation created with StrictDoc has to be exported to another tool and especially if the other tool has to export the content back to StrictDoc. Writing custom export/import generators may be needed to enable a full interoperability when the less portable features are used. @@ -2589,7 +2669,7 @@ The following is a list of features that are considered less portable when it co .. note:: It is easier to extend StrictDoc to produce a format supported by a given tool than it is to make the other tool export a 100%-identical content back to StrictDoc. If there is a need to interface with a tool X and something is missing in StrictDoc, please reach out to the developers (see [LINK: SDOC_UG_CONTACT]). -[/FREETEXT] +<<< [/SECTION] @@ -2597,19 +2677,21 @@ The following is a list of features that are considered less portable when it co UID: SDOC_UG_EXPERIMENTAL_FEATURES TITLE: Experimental features -[FREETEXT] +[TEXT] +STATEMENT: >>> At any point in time, StrictDoc supports features that are still experimental. These features are either not fully developed or their testing has not been completed yet. A feature is considered stable when all its known edge cases have been covered and enough users report that they have used and tested this feature. See also [LINK: SDOC_UG_CONFIG_FEATURES] for general instructions. -[/FREETEXT] +<<< [SECTION] UID: SECTION-UG-Project-statistics-screen TITLE: Project statistics screen -[FREETEXT] +[TEXT] +STATEMENT: >>> The project statistics screen displays useful information about a documentation project as well as some requirements-based statistics. To activate the project statistics screen, add/edit the ``strictdoc.toml`` config file in the root of your repository with documentation content. @@ -2624,7 +2706,7 @@ To activate the project statistics screen, add/edit the ``strictdoc.toml`` confi ] This feature is not enabled by default because it has not undergone sufficient testing by users. The particular aspect requiring extensive testing is related to StrictDoc's interaction with Git to retrieve git commit information. There remain certain unexamined edge cases and portability concerns, e.g., testing on Windows, testing projects that have no Git version control, calling StrictDoc outside of a project's root folder. -[/FREETEXT] +<<< [/SECTION] @@ -2711,7 +2793,8 @@ This feature is not enabled by default because it has not received enough testin [SECTION] TITLE: Shadow features -[FREETEXT] +[TEXT] +STATEMENT: >>> At any given moment, StrictDoc may contain one or more features that have been implemented and are supported in the codebase, yet lack documentation. In most cases, these features are still in their early stages and may not even be documented as experimental features. @@ -2719,7 +2802,7 @@ In most cases, these features are still in their early stages and may not even b The testing of these experimental features is typically done by developers or by selected users who have either requested or expressed interest in a specific feature. If you happen to stumble upon such a hidden feature, we encourage you to use it and provide bug reports or share your experiences with it. However, please be prepared to encounter various unknown or undefined behaviors in the process. -[/FREETEXT] +<<< [/SECTION] @@ -2733,9 +2816,10 @@ TITLE: StrictDoc's limitations UID: SDOC_UG_LIMIT_RST TITLE: Limitations of RST support by StrictDoc -[FREETEXT] +[TEXT] +STATEMENT: >>> StrictDoc uses Docutils for rendering RST to HTML, not Sphinx. The implication is that no Sphinx-specific RST directives are supported. Refer to this issue for the related discussion of the limitations: `Unexpected restriction on specific RST directives / compatibility with Breathe Sphinx Plugin #1093 `_. -[/FREETEXT] +<<< [/SECTION] @@ -2769,11 +2853,12 @@ The following essential features are still missing and will be worked on in the [SECTION] TITLE: Concurrent use of web user interface -[FREETEXT] +[TEXT] +STATEMENT: >>> StrictDoc's web user interface does not handle concurrency. If the same requirement/section is edited by two users at the same time, the last write wins. The measures for handling concurrent use are planned but have been not implemented yet. -[/FREETEXT] +<<< [/SECTION] @@ -2784,15 +2869,17 @@ The measures for handling concurrent use are planned but have been not implement [SECTION] TITLE: Known issues -[FREETEXT] +[TEXT] +STATEMENT: >>> This section documents some known issues and non-obvious implementation details. -[/FREETEXT] +<<< [SECTION] UID: SDOC_IMPL_2 TITLE: Running out of semaphores on macOS -[FREETEXT] +[TEXT] +STATEMENT: >>> This an edge case on macOS: Python crashes in the Parallelizer class when creating an output queue: @@ -2812,7 +2899,7 @@ The existing workaround for this problem is to increase a number of semaphores i .. code-block:: text sudo sysctl -w kern.posix.sem.max=20000 -[/FREETEXT] +<<< [/SECTION] diff --git a/docs/strictdoc_02_faq.sdoc b/docs/strictdoc_02_faq.sdoc index 1b7c5ec08..f43fac823 100644 --- a/docs/strictdoc_02_faq.sdoc +++ b/docs/strictdoc_02_faq.sdoc @@ -5,29 +5,32 @@ OPTIONS: REQUIREMENT_STYLE: Inline REQUIREMENT_IN_TOC: True -[FREETEXT] +[TEXT] +STATEMENT: >>> This document is a list of questions that people ask about StrictDoc. Missing a question or an answer? Ask it here: [LINK: SDOC_UG_CONTACT]. -[/FREETEXT] +<<< [SECTION] TITLE: What is StrictDoc? -[FREETEXT] +[TEXT] +STATEMENT: >>> 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. -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: Resources about StrictDoc -[FREETEXT] +[TEXT] +STATEMENT: >>> 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. @@ -43,14 +46,15 @@ Screencasts/tutorials: - `Automotive SPICE in opensource StrictDoc tool, with System Architecure ideas `_ by Lukasz Juranek. -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: Which web server is recommended for StrictDoc documentation? -[FREETEXT] +[TEXT] +STATEMENT: >>> 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. @@ -60,14 +64,15 @@ Is your project public or private? If it is public, you could simply use `GitHub 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. -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: Is StrictDoc compatible with Sphinx? -[FREETEXT] +[TEXT] +STATEMENT: >>> 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. @@ -80,14 +85,15 @@ There are users of StrictDoc who use both StrictDoc and Sphinx. The following wo - 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 `_. -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: How did the SDoc text language become what it is? -[FREETEXT] +[TEXT] +STATEMENT: >>> 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. ---- @@ -168,7 +174,7 @@ The support of multiline strings is arranged by a custom solution which helps to **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. -[/FREETEXT] +<<< [/SECTION] @@ -178,7 +184,8 @@ TITLE: How StrictDoc compares to other tools? [SECTION] TITLE: Doorstop -[FREETEXT] +[TEXT] +STATEMENT: >>> The StrictDoc project is a close successor of another project called `Doorstop `_. @@ -226,14 +233,15 @@ StrictDoc differs from Doorstop in a number of aspects: The roadmap of StrictDoc contains a work item for supporting the export/import to/from Doorstop format. -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: Sphinx -[FREETEXT] +[TEXT] +STATEMENT: >>> 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 @@ -250,14 +258,15 @@ 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 `_. -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: Sphinx-Needs -[FREETEXT] +[TEXT] +STATEMENT: >>> `Sphinx-Needs `_ is a text-based requirements management system based on Sphinx. It is implemented as a Sphinx extension which extends the @@ -310,14 +319,15 @@ The difference between Sphinx-Needs and StrictDoc: and `others `_. -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: FRET -[FREETEXT] +[TEXT] +STATEMENT: >>> `FRET `_ is a framework for the elicitation, specification, formalization and understanding of requirements. @@ -334,7 +344,7 @@ FRET has an impressive list of FRET's user interface is built with Electron. The detailed comparison is coming. -[/FREETEXT] +<<< [/SECTION] @@ -343,7 +353,8 @@ The detailed comparison is coming. [SECTION] TITLE: How long has the StrictDoc project been around? -[FREETEXT] +[TEXT] +STATEMENT: >>> The first StrictDoc commit dates back to ``2019-08-10``. A short development chronology of StrictDoc is as follows: **2019 – July – August** @@ -372,20 +383,21 @@ The custom RST parser was replaced with a TextX-based DSL. Since then, StrictDoc **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. -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: Which StrictDoc statistics are available? -[FREETEXT] +[TEXT] +STATEMENT: >>> Most relevant GitHub statistics: - `Contributors `_ The `pip trends `_ helps to visualize the Pip package download stats. The ``reqif`` satellite project is included for comparison as well: `strictdoc vs reqif `_. -[/FREETEXT] +<<< [/SECTION] diff --git a/docs/strictdoc_03_development_plan.sdoc b/docs/strictdoc_03_development_plan.sdoc index 8a0a3fca5..b52ffb280 100644 --- a/docs/strictdoc_03_development_plan.sdoc +++ b/docs/strictdoc_03_development_plan.sdoc @@ -4,15 +4,17 @@ OPTIONS: REQUIREMENT_STYLE: Table REQUIREMENT_IN_TOC: True -[FREETEXT] +[TEXT] +STATEMENT: >>> This document presents the goals of the StrictDoc project and describes how the project is developed. -[/FREETEXT] +<<< [SECTION] TITLE: Project goals -[FREETEXT] +[TEXT] +STATEMENT: >>> StrictDoc is an open-source tool for writing technical documentation and requirements management. The long-term goal of the project is to provide a capable, open-source platform for creating and managing technical documentation. **Requirements automation** @@ -34,7 +36,7 @@ An important feature of StrictDoc is its focus on open data, ensuring ease of da **Synergies with other tools** StrictDoc shall be compatible with other software and engineering tools. This includes at least the compatibility with the Python ecosystem, the model-based systems engineering tools, such as Capella, and the formats providing Software Bill of Materials, such as SPDX. -[/FREETEXT] +<<< [/SECTION] @@ -101,15 +103,15 @@ As an open-source project, StrictDoc is developed without strict deadlines, howe [SECTION] TITLE: The roadmap diagram -[FREETEXT] +[TEXT] +STATEMENT: >>> The following diagram contains the work items at the epic and single task levels. This PNG file is exported from a draw.io diagram, where the master version of the roadmap is maintained. .. image:: _assets/StrictDoc_Workspace-Roadmap.drawio.png :alt: Development plan diagram :class: image :width: 100% - -[/FREETEXT] +<<< [/SECTION] @@ -118,7 +120,8 @@ The following diagram contains the work items at the epic and single task levels [SECTION] TITLE: Verification -[FREETEXT] +[TEXT] +STATEMENT: >>> StrictDoc has three groups of tests: unit, integration, end-to-end tests. The unit tests are based on Pylint. @@ -126,19 +129,20 @@ The unit tests are based on Pylint. The integration tests are based on the `LLVM Integrated Tester `_ and `FileCheck.py `_. These tools are not very common, refer to `How to test command-line programs with Python tools: LIT and FileCheck `_ for a good description. The end-to-end web interface tests are based on SeleniumBase test framework. -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: Python baseline -[FREETEXT] +[TEXT] +STATEMENT: >>> The supported version of Python is kept to be as low as possible. As of 2024-Q4, the currently supported version is Python 3.8. Ideally, the lowest Python version should only be raised when it is consistently deprecated by the major software platforms like Ubuntu or GitHub Actions. Another reason for upgrading the minimum Python version is due to the upstream dependencies. As these dependencies stop supporting the older versions of Python, StrictDoc must be upgraded to maintain compatibility. With the existing dependency graph, this happens rather infrequently as most dependencies also maintain the compatibility with the older Python versions. -[/FREETEXT] +<<< [/SECTION] diff --git a/docs/strictdoc_04_release_notes.sdoc b/docs/strictdoc_04_release_notes.sdoc index 3649cbdc2..b6e321b0b 100644 --- a/docs/strictdoc_04_release_notes.sdoc +++ b/docs/strictdoc_04_release_notes.sdoc @@ -1,9 +1,10 @@ [DOCUMENT] TITLE: Release Notes -[FREETEXT] +[TEXT] +STATEMENT: >>> This document maintains a record of all changes to StrictDoc since November 2023. It serves as a user-friendly version of the changelog, complementing the automatically generated, commit-by-commit changelog available here: `StrictDoc Changelog `_. -[/FREETEXT] +<<< [SECTION] TITLE: 0.0.59 (2024-10-13) @@ -76,7 +77,8 @@ Other changes in this release: [SECTION] TITLE: 0.0.56 (2024-06-02) -[FREETEXT] +[TEXT] +STATEMENT: >>> This is an intermediate bugfix release before the release which will contain major changes. The following issues have been fixed: @@ -92,27 +94,29 @@ The following issues have been fixed: `backend/sdoc: allow using "DESCRIPTION" or "CONTENT" field instead of "STATEMENT" (#1827) `_ Previously only STATEMENT could be used as a reserved statement field. Now StrictDoc will auto-detect two more alternative fields if they are present: ``DESCRIPTION`` or ``CONTENT``. Thanks to @haxtibal for requesting this and explaining the use case. `pyproject.toml: update python-datauri (#1820) `_ @DomenicP reported an issue to ``python-datauri`` which StrictDoc depends on. They ``ran into an integration issue with the datauri library installing tests to the virtual environment. The library maintainer was kind enough to quickly resolve the issue in fcurella/python-datauri#14.`` Thanks @DomenicP! -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: 0.0.55 (2024-04-28) -[FREETEXT] +[TEXT] +STATEMENT: >>> The ReqIF export/import feature was extended to support three new command-line options for an improved export/import interfacing with Polarion. See [LINK: SECTION-UG-ReqIF-options] for more details. The Composable Documents feature was extended to support copying assets to the HTML output folder in a redundant way in the case when an included document is stored in a different directory than the parent including document. See https://github.com/strictdoc-project/strictdoc/issues/1777 for the problem definition. Thanks to @Briceus from StrictDoc's Discord channel for reporting this issue. StrictDoc's caching feature was extended to work around pickling errors when an outdated item is found in a cache. Such issues happen due to the (rare) refactorings in StrictDoc's data model. In this specific case, the previous ``FragmentFromFile`` Python class was renamed to ``DocumentFromFile`` and that caused problems when unpickling outdated cached content on a user machine. Thanks to @nashif for reporting this. -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: 0.0.54 (2024-04-17) -[FREETEXT] +[TEXT] +STATEMENT: >>> 1) Two improvements were made to the Composable Documents feature, when included document's root node is edited in including document: - If a document is included to another document, now it is possible to edit a title and a free text of the included document. @@ -121,45 +125,49 @@ TITLE: 0.0.54 (2024-04-17) 2) HTML2PDF feature was updated to support printing UTF8-based documents on Windows. 3) The feature that allows moving TOC (Table of Contents) nodes using drag-and-drop has been enhanced. Now, each TOC element maintains its open or closed state independently of its parent section. Previously, there was some dependency between child and parent TOC nodes, which made quick editing of the TOC more challenging. -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: 0.0.53 (2024-04-01) -[FREETEXT] +[TEXT] +STATEMENT: >>> The JSON export algorithm was extended to support composable documents. By default, the included documents are exported only as part of their including documents. To export both the including documents and included documents' standalone SDoc content, the option ``--included-documents`` option has to be specified with the ``export`` command. All code related to pybtex/BibTeX bibliographies has been removed from the StrictDoc project tree. This work was left unfinished for a long time and became unused legacy code over time. See the PR: `Remove all BibTeX bibliography-related code and pybtex dependency `_ for more explanation. -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: 0.0.52 (2024-03-25) -[FREETEXT] +[TEXT] +STATEMENT: >>> The **Grammar from File** feature has been implemented. Now it is possible to declare a usual StrictDoc ``[GRAMMAR]`` in a dedicated file with an ``.sgra`` extension. When a grammar is declared in a separate file, it is possible to share this grammar between several documents. Editing of the grammars defined in ``.sgra`` files can be only done with a text editor, it is not implemented yet in the editable web interface. -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: 0.0.51 (2024-03-20) -[FREETEXT] +[TEXT] +STATEMENT: >>> This is a bugfix release with only one change. A regression was introduced during recent internal refactoring, resulting in malfunctions on the Search screen when opening search links like "Find all requirements" or "Find all sections." This release fixes the introduced regression. -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: 0.0.50 (2024-03-19) -[FREETEXT] +[TEXT] +STATEMENT: >>> **Breaking change:** The "Fragments" feature has been replaced by the "Composable documents" feature: - The command ``[FRAGMENT_FROM_FILE]`` has been renamed to ``[DOCUMENT_FROM_FILE]``. @@ -173,14 +181,15 @@ TITLE: 0.0.50 (2024-03-19) **Other changes:** - The functionality of the HTML2PDF script on Windows has been corrected for scenarios where StrictDoc is operated within a virtual environment. Special thanks to @Timotheous for highlighting this issue. -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: 0.0.49 (2024-03-11) -[FREETEXT] +[TEXT] +STATEMENT: >>> The web interface code has been extended to allow editing arbitrary nodes. Previously, only editing the REQUIREMENT type was possible. From now on, it is possible to use the web interface to create custom grammar elements and nodes of corresponding grammar element types. A basic JSON export feature has been added. Now it is possible to export a StrictDoc project tree to a single JSON file with a structure that mirrors the structure of the SDoc grammar. @@ -192,14 +201,15 @@ The layout of the PDF document generated by the HTML2PDF conversion process has The source file identification mechanism of the requirement-to-source traceability feature has been expanded to locate all source files present in a given source input directory. Previously, it was limited to finding files with specific extensions such as .c, .py, .sdoc, .rst, among others. This restriction, originally implemented for historical reasons, has now been removed. Moreover, StrictDoc has now integrated the ``get_lexer_by_name()`` function to automatically identify a lexer based on a source file's extension. This enhancement help StrictDoc to offer syntax highlighting tailored specifically to the format of each source file. Previously, StrictDoc's code directly hardcoded only a limited selection of Pygments' lexers. Thanks to @KlfJoat for helping us to prioritize and fix this issue sooner. The Excel export algorithm was extended to support generating multiple Excel files for documentation tree with requirements that link to each other across documents. The issue manifested itself as ``KeyError``. Thanks to @Dynteq for reporting this. -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: 0.0.48 (2024-01-24) -[FREETEXT] +[TEXT] +STATEMENT: >>> The requirement-to-source traceability feature was extended to support linking requirements to the RST files. One more input scenario was handled for the Create Document workflow. When a project config has ``include_doc_paths`` or ``exclude_doc_paths`` filters specified, and an input document path contradicts to the provided filters, a validation message is shown. @@ -213,14 +223,15 @@ The Project Statistics screen was extended with the **"Sections without any text The Requirements Coverage has been transformed into **the Traceability Matrix** screen. This matrix screen lists all nodes of a documentation graph, along with all their interrelations. The currently generated screen is entirely static. However, future enhancements are planned to include filtering capabilities for the content. The Traceability Matrix feature is disabled by default and has to be activated as ``TRACEABILITY_MATRIX_SCREEN`` in the strictdoc.toml project config file. **The HTML2PDF feature** has now entered the alpha testing phase. This feature enables printing of documents directly from a browser, which can be done either through the "PDF" screen view or by utilizing the "Export to PDF" button. By default, the HTML2PDF feature is disabled. To activate it, you need to indicate the ``HTML2PDF`` feature in the strictdoc.toml project configuration file. -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: 0.0.47 (2023-11-20) -[FREETEXT] +[TEXT] +STATEMENT: >>> A **query search engine** is introduced which allows filtering a documentation tree by queries like ``(node.is_requirement and "System" in node["TITLE"])``. Building on the search engine capability, the "Search" screen is introduced in the web interface. Additionally, it is now possible to specify ``--filter-requirements `` and ``filter-sections `` when running ``export`` and ``passthrough`` commands. The visual design of the project statistics was improved as well as the new design for the search screen has already landed. @@ -237,6 +248,6 @@ Python 3.12 support has been added to the GitHub CI jobs. The second generation of StrictDoc's requirements received many updates. The new requirements set will be incorporated to the main documentation very soon (estimated time is until the end of 2023). These requirements are maintained in the ``drafts/requirements`` folder. The User Guide has been updated to include the **"Security Considerations" chapter**, which provides a warning about unsafe use of StrictDoc if it is deployed to a server on a public network. -[/FREETEXT] +<<< [/SECTION] diff --git a/docs/strictdoc_10_contributing.sdoc b/docs/strictdoc_10_contributing.sdoc index 338ce9b6e..d04fdc3a1 100644 --- a/docs/strictdoc_10_contributing.sdoc +++ b/docs/strictdoc_10_contributing.sdoc @@ -1,16 +1,18 @@ [DOCUMENT] TITLE: Contributing to StrictDoc -[FREETEXT] +[TEXT] +STATEMENT: >>> Contributions to StrictDoc are welcome and appreciated. Presented below is a condensed checklist that summarises the information of the development guide, see [LINK: DEVGUIDE_GETTING_STARTED]. -[/FREETEXT] +<<< [SECTION] TITLE: Contributor checklist -[FREETEXT] +[TEXT] +STATEMENT: >>> Before opening your Pull Request, the contributor is encouraged to do the following steps: @@ -25,7 +27,7 @@ following steps: single contribution. 4. If the contribution is not trivial, read through the complete development guide. -[/FREETEXT] +<<< [/SECTION] @@ -35,37 +37,40 @@ TITLE: How can I help? [SECTION] TITLE: Spread the word -[FREETEXT] +[TEXT] +STATEMENT: >>> If you like the StrictDoc project and use it in your daily work, there are several things you could do besides contributing Pull Requests: - Star the StrictDoc repository to show your appreciation of the project. - Write a blog post or a tutorial about using StrictDoc to achieve some goal. - Write an email to s.pankevich@gmail.com and mettta@gmail.com and tell us how you are using StrictDoc and which features you are missing. We somewhat lack enough feedback from our users. -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: ReqIF users -[FREETEXT] +[TEXT] +STATEMENT: >>> The existing capability of StrictDoc to export/import SDoc to ReqIF is very basic. If you have to deal with ReqIF and you experience errors/crashes when using StrictDoc against ReqIF files, feel free to contribute the anonymized ReqIF files via StrictDoc Issues on GitHub, and we will take care of your specific case. It is straightforward to create an anonymized version of a ReqIF file. Just reduce your file to the section that causes troubles in import or export and replace all your business-specific titles/texts to some ``Lorem ipsum...`` boilerplate, see https://www.loremipsum.de/. -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: TeX / LaTeX / Sphinx experts -[FREETEXT] +[TEXT] +STATEMENT: >>> The existing template for generating PDF documents using Sphinx looks like this: https://strictdoc.readthedocs.io/_/downloads/en/latest/pdf/. The template is maintained in a separate repository: https://github.com/strictdoc-project/sphinx-latex-reqspec-template and does a good job but could be improved in terms of look and structure used. If you are an expert and have experience of customizing Sphinx/TeX templates, consider providing feedback or contributing patches. One extreme way of improving the generated output could be to take the Sphinx template for TeX files and fully customize what Sphinx does to produce a PDF. See https://www.sphinx-doc.org/en/master/latex.html. -[/FREETEXT] +<<< [/SECTION] diff --git a/docs/strictdoc_11_developer_guide.sdoc b/docs/strictdoc_11_developer_guide.sdoc index dcbebf15f..a65e02b34 100644 --- a/docs/strictdoc_11_developer_guide.sdoc +++ b/docs/strictdoc_11_developer_guide.sdoc @@ -1,7 +1,8 @@ [DOCUMENT] TITLE: Developer Guide -[FREETEXT] +[TEXT] +STATEMENT: >>> This section contains everything that a StrictDoc developer/contributor should know to get the job done. @@ -13,7 +14,7 @@ The instructions and conventions described below are a summary of what is considered to be the currently preferred development style for StrictDoc. Any feedback on this development guide is appreciated. -[/FREETEXT] +<<< [SECTION] UID: DEVGUIDE_GETTING_STARTED @@ -22,7 +23,8 @@ TITLE: Getting started [SECTION] TITLE: System dependencies -[FREETEXT] +[TEXT] +STATEMENT: >>> StrictDoc itself mostly depends on other Python Pip packages, so there is nothing special to be installed. You may need to install ``libtidy`` if you want to run the integration tests. The HTML markup validation tests depend on libtidy. @@ -38,16 +40,17 @@ From the core Python packages, StrictDoc needs Invoke, Tox and TOML: .. code:: bash pip install invoke tox toml -[/FREETEXT] +<<< [SECTION] TITLE: Windows-specific: Long Path support -[FREETEXT] +[TEXT] +STATEMENT: >>> As `reported `_ by a user, Windows Long Path support has to be enabled on a Windows system. You can find information on how to enable the long paths support at https://pip.pypa.io/warnings/enable-long-paths. -[/FREETEXT] +<<< [/SECTION] @@ -56,7 +59,8 @@ You can find information on how to enable the long paths support at https://pip. [SECTION] TITLE: Installing StrictDoc from GitHub (developer mode) -[FREETEXT] +[TEXT] +STATEMENT: >>> **Note:** Use this way of installing StrictDoc only if you want to make changes in StrictDoc's source code. Otherwise, install StrictDoc as a normal Pip package by running ``pip install strictdoc``. @@ -67,7 +71,7 @@ in StrictDoc's source code. Otherwise, install StrictDoc as a normal Pip package python3 strictdoc/cli/main.py The ``pip_install_strictdoc_deps.py`` installs all dependencies of StrictDoc, but not StrictDoc itself. -[/FREETEXT] +<<< [/SECTION] @@ -76,7 +80,8 @@ The ``pip_install_strictdoc_deps.py`` installs all dependencies of StrictDoc, bu [SECTION] TITLE: Invoke for development tasks -[FREETEXT] +[TEXT] +STATEMENT: >>> All development tasks are managed using `Invoke `_ in the ``tasks.py`` file. On macOS and Linux, all tasks run in dedicated virtual environments. On Windows, invoke uses @@ -88,14 +93,15 @@ Make sure to familiarize yourself with the available developer tasks by running: .. code-block:: bash invoke --list -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: Main "Check" task -[FREETEXT] +[TEXT] +STATEMENT: >>> Before doing anything else, run the main ``check`` command to make sure that StrictDoc passes all tests on your system: .. code:: bash @@ -103,7 +109,7 @@ Before doing anything else, run the main ``check`` command to make sure that Str invoke check The ``check`` command runs all StrictDoc lint and test tasks with the only exception of end-to-end Web tests that are run with a separate task (see below). -[/FREETEXT] +<<< [/SECTION] @@ -111,7 +117,8 @@ The ``check`` command runs all StrictDoc lint and test tasks with the only excep UID: DEVGUIDE_PYTHON_CODE TITLE: Python code -[FREETEXT] +[TEXT] +STATEMENT: >>> - The version of Python is set to be as low as possible given some constraints of StrictDoc's dependencies. Ideally, the lowest Python version should only be raised when it is consistently deprecated by major software platforms like @@ -142,7 +149,7 @@ TITLE: Python code both unit and integration tests is preferred. The only exception where a contribution can contain no tests is "code climate" which is work which introduces changes in code but no change to the functionality. -[/FREETEXT] +<<< [/SECTION] @@ -150,7 +157,8 @@ TITLE: Python code UID: DEVGUIDE_GIT_WORKFLOW TITLE: Git workflow -[FREETEXT] +[TEXT] +STATEMENT: >>> - The preferred Git workflow is "1 commit per 1 PR". If the work truly deserves a sequence of commits, each commit shall be self-contained and pass all checks from the ``invoke check`` command. The preferred approach: split the work into @@ -188,38 +196,41 @@ where the context can be a major feature being added or a folder. A form of ``c .. code-block:: Code climate: fix all remaining major Pylint warnings -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: Frontend development -[FREETEXT] +[TEXT] +STATEMENT: >>> The shortest path to run the server when the StrictDoc's source code is cloned: .. code-block:: bash invoke server -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: Running End-to-End Web tests -[FREETEXT] +[TEXT] +STATEMENT: >>> .. code:: bash invoke test-end2end -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: Running integration tests -[FREETEXT] +[TEXT] +STATEMENT: >>> The integration tests are run using Invoke: .. code-block:: bash @@ -233,14 +244,15 @@ The ``--focus`` parameter can be used to run only selected tests that match a gi invoke test-integration --focus See `How to test command-line programs with Python tools: LIT and FileCheck `_ to learn more about LIT and FileCheck, which enable the StrictDoc integration tests. -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: Documentation -[FREETEXT] +[TEXT] +STATEMENT: >>> - Every change in the functionality or the infrastructure should be documented. - Every line of documentation shall be no longer than 80 characters. StrictDoc's own documentation has a few exceptions, however, the latest preference is @@ -249,18 +261,19 @@ TITLE: Documentation split by a contributor manually. - The ``invoke docs`` task should be used for re-generating documentation on a developer machine. -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: Conventions -[FREETEXT] +[TEXT] +STATEMENT: >>> - ``snake_case`` everywhere, no ``kebab-case``. - This rule applies everywhere where applicable: file and folder names, HTML attributes. - Exception: HTML data-attributes and ``testid`` identifiers. -[/FREETEXT] +<<< [/SECTION] diff --git a/docs/strictdoc_20_L1_Open_Requirements_Tool.sdoc b/docs/strictdoc_20_L1_Open_Requirements_Tool.sdoc index f8d846f3d..fa8accb29 100644 --- a/docs/strictdoc_20_L1_Open_Requirements_Tool.sdoc +++ b/docs/strictdoc_20_L1_Open_Requirements_Tool.sdoc @@ -43,7 +43,8 @@ ELEMENTS: - TYPE: Parent - TYPE: File -[FREETEXT] +[TEXT] +STATEMENT: >>> The StrictDoc project is structured around two distinct requirement documents that guide its development: 1. The "Requirements Tool Specification" (this document), which is a higher-level document. @@ -52,25 +53,27 @@ The StrictDoc project is structured around two distinct requirement documents th This document, the Requirements Tool Specification, delineates the general requirements for an open-source Requirements Tool, with a focus that remains agnostic of the specific implementation details of StrictDoc. Its primary goal is to provide a comprehensive, implementation-neutral overview of what capabilities a Requirements Tool should possess, emphasizing the 'WHAT' aspect. In contrast, the StrictDoc Requirements Specification, the second document, delves deeply into the 'HOW' aspect of StrictDoc’s implementation. It builds upon the high-level requirements set out in this document, treating them as parent requirements to guide its detailed development approach. -[/FREETEXT] +<<< [SECTION] MID: 668d18a7489043b38dd435933319e8e7 TITLE: Summary of user needs -[FREETEXT] +[TEXT] +STATEMENT: >>> This section offers an overview of the necessary capabilities of a requirements and documentation management tool. -[/FREETEXT] +<<< [SECTION] MID: 1cbe275272994922a942fd088fa969d8 TITLE: Free and open source tool -[FREETEXT] +[TEXT] +STATEMENT: >>> The primary user need and entry point for this Requirements Tool specification is the availability of free, lightweight, yet capable software for creating requirements specifications and other technical documentation. The tool should facilitate the creation of requirements specifications and technical documents, effectively lowering the entry barrier for requirements engineering and technical documentation writing. It is assumed throughout this document that the requirements tool will be developed as open-source software available at no cost. However, with minor adjustments, these requirements could also apply to commercial requirements tools. See [LINK: SECTION-SSSS-Licensing-and-distribution]. -[/FREETEXT] +<<< [/SECTION] @@ -78,7 +81,8 @@ It is assumed throughout this document that the requirements tool will be develo MID: 18136bcb9a5b4226a7a95d27dae49805 TITLE: Document types -[FREETEXT] +[TEXT] +STATEMENT: >>> A requirements tool is very often also a documentation writing and management tool, so, besides the requirements editing functionality, the tool shall be able to accommodate for the variety of documents and templates used in different industries. The variety comes from: @@ -98,14 +102,15 @@ Examples of typical document types include: - Standard (e.g., ECSS or ISO 26262). The documentation/requirements management requirements for a Requirements Tool are specified in the sections [LINK: SECTION-RTS-Documentation-management] and [LINK: SECTION-RTS-Requirements-management]. -[/FREETEXT] +<<< [SECTION] MID: 973b586b8a89411ab4f083fd4c262cf5 UID: SECTION-RTC-Appendix-A-Document-archetypes TITLE: Document structure differences -[FREETEXT] +[TEXT] +STATEMENT: >>> The table below summarizes various differences observed across industry documents. .. list-table:: Table: Requirements and specification document @@ -123,7 +128,7 @@ The table below summarizes various differences observed across industry document - Some documents provide UIDs for all requirements, some do not. Where the UIDs are missing, the section header numbers are used instead for unique identification. Often, a combination "Number + Title" becomes a reference-able identifier. * - Requirement titles - Not all documents provide requirement titles. When the requirement titles are missing, the grouping is may be provided by sections/chapters. When the titles are present, the requirement titles can also be section titles. -[/FREETEXT] +<<< [/SECTION] @@ -134,7 +139,8 @@ MID: 52b6175f03d7495a9fa8dbffa36aeff4 UID: SECTION-LRTS-Workflows TITLE: Workflows -[FREETEXT] +[TEXT] +STATEMENT: >>> Besides supporting a variety of document types, a Requirements Tool shall also support and integrate well with multiple documentation and requirements management workflows. At least the following workflows have been identified to be relevant: @@ -168,7 +174,7 @@ At least the following workflows have been identified to be relevant: - Supporting seamless integration between a project documentation tree and applicable standards. The section [LINK: SECTION-SSSS-Existing-workflows] contains the workflow-related requirements for a Requirements Tool. -[/FREETEXT] +<<< [/SECTION] @@ -176,7 +182,8 @@ The section [LINK: SECTION-SSSS-Existing-workflows] contains the workflow-relate MID: 08d547a3b04d485ca1f5a3a94a664ee1 TITLE: Target audience -[FREETEXT] +[TEXT] +STATEMENT: >>> A Requirements Tool may have different users, each with a different role, experience and background which necessitates the requirements towards usability, installation, and user experience. The following user groups are preliminarily identified as especially relevant: @@ -208,7 +215,7 @@ This group of users may not work with a Requirements Tool directly but is still Not all users of a requirements tool must have an engineering background. In fact, there are many projects where non-technical people have to maintain requirements. The Requirements Tool shall be usable without any technical training required, featuring an intuitive user interface and simplified processes for entering and managing requirements. The requirement sets in the sections [LINK: SECTION-RTC-Usability-installation-and-usage] and [LINK: SECTION-SSSS-Implementation-suggestions] aim to equip the Requirements Tool with sufficient capabilities to support all of the user groups described above. -[/FREETEXT] +<<< [/SECTION] @@ -219,7 +226,8 @@ MID: f1ffdc7f78134d4b98f3c90e9be40cc7 UID: SECTION-RTS-Documentation-management TITLE: Documentation management -[FREETEXT] +[TEXT] +STATEMENT: >>> This section outlines the requirements towards a Requirements Tool as a documentation tool. The requirements of this group are dedicated to the core tasks of documentation management: @@ -227,7 +235,7 @@ The requirements of this group are dedicated to the core tasks of documentation - Writing, structuring and managing documents - Complementing documents with meta information - Versioning documents. -[/FREETEXT] +<<< [REQUIREMENT] MID: 72d0dd23dedd4907b4a8924debe7343b @@ -324,7 +332,8 @@ MID: fd227b9cfdc54d7db3134cdb925bde87 UID: SECTION-RTS-Requirements-management TITLE: Requirements management -[FREETEXT] +[TEXT] +STATEMENT: >>> This section outlines the requirements towards a Requirements Tool as a requirements management tool. The following core aspects of the requirements management are covered: @@ -333,7 +342,7 @@ The following core aspects of the requirements management are covered: - Linking requirements with other requirements - Managing requirement unique identifiers (UID) - Requirement verification. -[/FREETEXT] +<<< [REQUIREMENT] MID: 6e6f1464c47f4ced8e14c4153f40618b @@ -574,9 +583,10 @@ MID: 56dabce670be4691b35434bda6d6bb36 UID: SECTION-SSSS-Performance TITLE: Performance -[FREETEXT] +[TEXT] +STATEMENT: >>> This section captures the performance requirements towards a Requirements Tool. -[/FREETEXT] +<<< [REQUIREMENT] MID: a0a95079e3c0438bb3ea9e5af7ddddc9 @@ -624,9 +634,10 @@ MID: ec52fa5cc1714b07863eb7da9432be1d UID: SECTION-SSSS-Existing-workflows TITLE: Existing workflows -[FREETEXT] +[TEXT] +STATEMENT: >>> This section captures the requirements towards specific workflows that a Requirements Tool should support as outlined in [LINK: SECTION-LRTS-Workflows]. -[/FREETEXT] +<<< [REQUIREMENT] MID: 831debedfa0e4e4c8434021569f96bad @@ -972,10 +983,11 @@ MID: 7bdea1a7cb9e4f6fbcf8497670f87278 UID: SECTION-RTS-Text-based-requirements-language TITLE: Text-based requirements language (optional) -[FREETEXT] +[TEXT] +STATEMENT: >>> Note: Not all requirements tools must be text-based. But when they are, the following requirements apply. -[/FREETEXT] +<<< [REQUIREMENT] MID: f472e85f3398413795234a9298d4af3c @@ -1051,11 +1063,12 @@ MID: cd9e353e07ae4d50b1aa08999854aa02 UID: SECTION-RTS-Requirements-exchange-formats-export-import TITLE: Requirements exchange formats (export/import) -[FREETEXT] +[TEXT] +STATEMENT: >>> This section captures the requirements related to "Requirements exchange" as outlined in the section [LINK: SECTION-LRTS-Workflows]. The Requirements Tool should fundamentally support the exchange of documentation and requirements with other tools. Importing data into this tool and exporting data from it to other tools should be straightforward. The key focus of this section's requirements is on enabling seamless access to requirements and documentation data. -[/FREETEXT] +<<< [REQUIREMENT] MID: 73e70548c2cf415f94adbf1066d5fe4b @@ -1181,9 +1194,10 @@ MID: e4cd429e9ec04deabfd1fb1381c39e38 UID: SECTION-SSSS-Licensing-and-distribution TITLE: Licensing and distribution -[FREETEXT] +[TEXT] +STATEMENT: >>> This section outlines the requirements for the "free and open source" aspect of the Requirements Tool. -[/FREETEXT] +<<< [REQUIREMENT] MID: 2f30b94fdc074c8fa5858dfccc6202e8 diff --git a/docs/strictdoc_25_design.sdoc b/docs/strictdoc_25_design.sdoc index 991055b92..9c6dc4119 100644 --- a/docs/strictdoc_25_design.sdoc +++ b/docs/strictdoc_25_design.sdoc @@ -5,28 +5,31 @@ OPTIONS: REQUIREMENT_STYLE: Table REQUIREMENT_IN_TOC: True -[FREETEXT] +[TEXT] +STATEMENT: >>> This document describes the architecture and the implementation details of StrictDoc. Compared to the User Guide that describes how to use StrictDoc, this Design Document focuses on the "how it works" of StrictDoc. -[/FREETEXT] +<<< [SECTION] TITLE: Overview -[FREETEXT] +[TEXT] +STATEMENT: >>> StrictDoc consists of two applications: 1. StrictDoc command-line application (CLI). 2. StrictDoc web application. Both applications share a significant subset of the backend and frontend logic. The backend logic is written in Python, the frontend logic is written using HTML/CSS, Jinja templates, and a combination of Turbo.js/Stimulus.js frontend libraries. -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: Building blocks -[FREETEXT] +[TEXT] +STATEMENT: >>> StrictDoc is based on the following open-source libraries and tools: .. list-table:: @@ -56,7 +59,7 @@ StrictDoc is based on the following open-source libraries and tools: * - Selenium and SeleniumBase - Used for end-to-end testing of StrictDoc's Web-based user interface. -[/FREETEXT] +<<< [/SECTION] @@ -64,21 +67,23 @@ StrictDoc is based on the following open-source libraries and tools: UID: SECTION-DD-High-level-architecture TITLE: High-level architecture -[FREETEXT] +[TEXT] +STATEMENT: >>> The following diagram captures the high-level architecture of StrictDoc. .. image:: _assets/StrictDoc_Architecture.drawio.png :alt: StrictDoc's architecture diagram :class: image :width: 100% -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: StrictDoc command-line application -[FREETEXT] +[TEXT] +STATEMENT: >>> StrictDoc command-line application is at the core of StrictDoc. The command-line interface contains commands for exporting/importing SDoc content from/to other formats and presenting documentation content to a user. The command-line application can be seen as a Model-View-Controller application: @@ -87,26 +92,28 @@ The command-line application can be seen as a Model-View-Controller application: - Depending on the type of command, a responsible Action (Controller layer) processes the command (export action, import action, etc.). - The input of the command is transformed by the action using the backend (Model layer) (SDoc, ReqIF, Excel, etc.). - The resulting output is written back to HTML or other formats (View layer). -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: StrictDoc web application -[FREETEXT] +[TEXT] +STATEMENT: >>> StrictDoc Web application is based on FastAPI / Uvicorn. The end-to-end usage cycle of the web application is as follows: - A browser requests documents from a FastAPI server. - The FastAPI web server parses the SDoc files into memory and converts them into HTML using Jinja templates. The resulting HTML output is given back to the user. - The Jinja templates are extended with JavaScript logic that allows a user to edit the documents and send the updated content back to the server. - The server writes the updated content back to the SDoc files stored on a user's file system. -[/FREETEXT] +<<< [SECTION] TITLE: The HTML Over the Wire (Hotwire) architecture -[FREETEXT] +[TEXT] +STATEMENT: >>> StrictDoc uses the `Hotwire architecture `_. The JavaScript framework used by StrictDoc is minimized to Turbo.js/Stimulus.js which helps to avoid the complexity of the larger JS frameworks such as React, Vue, Angular, etc. In accordance with the Hotwire approach, most of the StrictDoc's business logic is done on a server, while Turbo and Stimulus provide a thin layer of JS and AJAX to connect the almost static HTML with the server. @@ -114,7 +121,7 @@ The JavaScript framework used by StrictDoc is minimized to Turbo.js/Stimulus.js The Hotwire approach helps to reduce the differences between the static HTML produced by the StrictDoc command-line application and the StrictDoc web application. In both cases, the core content of StrictDoc is a statically generated website with documents. The web application extends the static HTML content with Turbo/Stimulus to turn it into a dynamic website. Currently, the web server renders the HTML documents using the same generators that are used by the static HTML export, so the static HTML documentation and the web application interface look identical. The web interface adds the action buttons and other additional UI elements for editing the content. -[/FREETEXT] +<<< [/SECTION] @@ -123,7 +130,8 @@ Currently, the web server renders the HTML documents using the same generators t [SECTION] TITLE: Parsing SDoc files -[FREETEXT] +[TEXT] +STATEMENT: >>> StrictDoc uses `textX `_ which is a ``meta-language for building Domain-Specific Languages (DSLs) in Python``. The textX itself is based on `Arpeggio `_ which is a ``Parser interpreter based on PEG grammars written in Python``. StrictDoc relies on both tools to get: @@ -133,7 +141,7 @@ StrictDoc relies on both tools to get: - Fast parsing of SDoc files. One important implementation detail of Arpeggio that influences StrictDoc user experience is that the parser stops immediately when it encounters an error. For a document that has several issues, the parser highlights only the first error without going any further. When the first error is resolved, the second error will be shown, etc. -[/FREETEXT] +<<< [/SECTION] diff --git a/docs/strictdoc_28_Backlog.sdoc b/docs/strictdoc_28_Backlog.sdoc index 3667ec078..ce7f1befc 100644 --- a/docs/strictdoc_28_Backlog.sdoc +++ b/docs/strictdoc_28_Backlog.sdoc @@ -42,23 +42,25 @@ ELEMENTS: - TYPE: Parent - TYPE: File -[FREETEXT] +[TEXT] +STATEMENT: >>> This document outlines the future work items for StrictDoc. The following items are listed in descending order of priority, with the topmost items either currently in progress or scheduled to be implemented next. While this backlog overlaps with StrictDoc's `GitHub issues tracker `_ by more than 50%, it includes more strategic items compared to the GitHub issues, which are primarily focused on actual implementation work. -[/FREETEXT] +<<< [SECTION] MID: d1e697dea73144c48a4b88d0d784a517 UID: SECTION-SB-Open-source-requirements-tool-challenges TITLE: StrictDoc challenges -[FREETEXT] +[TEXT] +STATEMENT: >>> - Limited development time. - Not easy to develop certain capabilities and scale to a multi-user environment quickly. -[/FREETEXT] +<<< [REQUIREMENT] MID: fc76b207c152433888a86a166f58a425 @@ -476,7 +478,8 @@ MID: 4a49c79a1bdd4d4aae5f62bc1d2a56d0 UID: SECTION-SB-Backlog-Web-based-user-interface TITLE: Backlog: Web-based user interface -[FREETEXT] +[TEXT] +STATEMENT: >>> - Uploading images via Web interface. - Deleting sections recursively. Correct clean-up of all traceability information. @@ -504,7 +507,7 @@ TITLE: Backlog: Web-based user interface - ReqIF: Export complete documentation tree or a single document. - ReqIF: Import complete documentation tree or a single document. -[/FREETEXT] +<<< [/SECTION] @@ -513,7 +516,8 @@ MID: 866a55f2e47b477ebcd52ea57da4f037 UID: SECTION-SB-Backlog-Nice-to-have TITLE: Backlog: Nice to have -[FREETEXT] +[TEXT] +STATEMENT: >>> - Configuration file options: - CLI command to dump default config file @@ -542,7 +546,7 @@ TITLE: Backlog: Nice to have - **Partial evaluation of Jinja templates.** Many of the template variables could be made to be evaluated once, for example, config object's variables. - UI version for mobile devices (at least some basic tweaks). -[/FREETEXT] +<<< [/SECTION] @@ -551,12 +555,13 @@ MID: eb1fab2bbea541c8b00f70780326c9fc UID: SECTION-SB-Backlog-Technical-debt TITLE: Backlog: Technical debt -[FREETEXT] +[TEXT] +STATEMENT: >>> - When a document is added, the whole documentation is rebuilt from the file system from scratch. A more fine-grained re-indexing of documentation tree can be implemented. The current idea is to introduce a layer of pickled cached data: preserve the whole in-memory traceability graph in a cache, and then use the cached data for making decisions about what should be regenerated. - The "no framework" approach with FastAPI and Turbo/Stimulus allows writing almost zero Javascript, however some proto-framework conventions are still needed. Currently, all code is written in the ``main_controller`` which combines all responsibilities, such as parsing HTTP request fields, accessing traceability graph, validations, rendering back the updated AJAX templates. A lack of abstraction is better than a poor abstraction, but some solution has to be found. - Request form object vs Response form object. The workflow of form validations is not optimal. - For Web development, the responsibilities of the ``TraceabilityIndex`` class compared to the ``ExportAction``, ``MarkupRenderer``, ``LinkRenderer`` classes are unstable. A more ecological composition of classes has to be found. ``Traceability`` index is rightfully a "god object" because it contains all information about the in-memory documentation graph. -[/FREETEXT] +<<< [/SECTION] @@ -570,7 +575,8 @@ MID: 717df91623014fb98ba34ab8173b94ab UID: SECTION-SB-One-or-many-input-sdoc-trees TITLE: One or many input sdoc trees -[FREETEXT] +[TEXT] +STATEMENT: >>> StrictDoc supports this for HTML already but not for RST. When passed @@ -592,7 +598,7 @@ space with cross-linking possible. The question is if it is worth supporting this case further or StrictDoc should only work with one input folder with a single doc tree. -[/FREETEXT] +<<< [/SECTION] diff --git a/docs/strictdoc_30_credits.sdoc b/docs/strictdoc_30_credits.sdoc index 4d97a8d36..cce43e1cd 100644 --- a/docs/strictdoc_30_credits.sdoc +++ b/docs/strictdoc_30_credits.sdoc @@ -1,7 +1,8 @@ [DOCUMENT] TITLE: Credits -[FREETEXT] +[TEXT] +STATEMENT: >>> As an open-source project, StrictDoc is based on the work of many people and organizations: - StrictDoc receives contributions from other developers. @@ -10,12 +11,13 @@ As an open-source project, StrictDoc is based on the work of many people and org - StrictDoc uses the commercial versions of JetBrains IDEs for free. This page gives due credit to everyone who made StrictDoc possible. -[/FREETEXT] +<<< [SECTION] TITLE: Contributions to StrictDoc -[FREETEXT] +[TEXT] +STATEMENT: >>> The core team: @stanislaw and @mettta. The following people and organizations have contributed to StrictDoc. The contributions are listed in the alphabetic order. @@ -32,14 +34,15 @@ Companies: - `Kontrol `_ have sponsored the work related to the early implementation of the ReqIF import/export feature (@alex.d, @cbernt, @Relasym). Single/smaller contributions can be also seen on the `StrictDoc's Insights/Contributors `_ page. -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: Open source software -[FREETEXT] +[TEXT] +STATEMENT: >>> StrictDoc is based on other open source components. Without this support, we would have never reached where we are today. StrictDoc was heavily inspired by the `Doorstop `_ project. Without the strong example of Doorstop, StrictDoc would probably never exist. @@ -61,25 +64,27 @@ StrictDoc uses `XlsxWriter `_ and `xlrd `_ for an up-to-date summary of StrictDoc's dependencies. -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: Hosting and Continuous Integration -[FREETEXT] +[TEXT] +STATEMENT: >>> StrictDoc is hosted on `GitHub `_ and uses `GitHub Actions `_ to run all of its build, test and release tasks. As an open-source project, StrictDoc gets these services from GitHub for free. StrictDoc's documentation is hosted on `Read the Docs `_. -[/FREETEXT] +<<< [/SECTION] [SECTION] TITLE: Commercial IDEs by JetBrains -[FREETEXT] +[TEXT] +STATEMENT: >>> The StrictDoc's core team uses the commercial versions of `PyCharm `_ and @@ -89,6 +94,6 @@ from `JetBrains `_. The `Licenses for Open Source Development - Community Support `_ from JetBrains are provided to the core team for free, based on the precondition that StrictDoc is developed as completely free software, without any monetization mechanisms. Before the license for the commercial JetBrains was obtained in 2023, the complete StrictDoc's Python codebase had been produced using `PyCharm, the Community edition `_. -[/FREETEXT] +<<< [/SECTION] diff --git a/docs_extra/DO178_requirements.sdoc b/docs_extra/DO178_requirements.sdoc index bc7c9a9e3..643f0f3dd 100644 --- a/docs_extra/DO178_requirements.sdoc +++ b/docs_extra/DO178_requirements.sdoc @@ -53,11 +53,12 @@ ELEMENTS: RELATIONS: - TYPE: Parent -[FREETEXT] +[TEXT] +STATEMENT: >>> This document outlines a set of high-level requirements for StrictDoc, a text-based requirements management system. While StrictDoc already meets many of these requirements, a further discussion is needed to clarify any remaining questions. For the outstanding requirements, we can establish a practical implementation plan within the upcoming 2023-2024 StrictDoc roadmap. These requirements are recommended by engineers who adhere to the DO-178B and DO-178C standards of the aviation industry. For a visual summary of the DO-178 standard, please refer to this link: https://upload.wikimedia.org/wikipedia/commons/4/4f/DO-178B_Process_Visual_Summary_Rev_A.pdf. -[/FREETEXT] +<<< [SECTION] MID: 6be4dbe02b4346df9849eaa6fe077e0e