diff --git a/docs/sphinx/source/_assets/Feature_Screenshot_DiffChangelog_1.png b/docs/sphinx/source/_assets/Feature_Screenshot_DiffChangelog_1.png new file mode 100644 index 000000000..167fad28b Binary files /dev/null and b/docs/sphinx/source/_assets/Feature_Screenshot_DiffChangelog_1.png differ diff --git a/docs/sphinx/source/_assets/Feature_Screenshot_DiffChangelog_2.png b/docs/sphinx/source/_assets/Feature_Screenshot_DiffChangelog_2.png new file mode 100644 index 000000000..83e2503e7 Binary files /dev/null and b/docs/sphinx/source/_assets/Feature_Screenshot_DiffChangelog_2.png differ diff --git a/docs/sphinx/source/_assets/Feature_Screenshot_Grammar.png b/docs/sphinx/source/_assets/Feature_Screenshot_Grammar.png new file mode 100644 index 000000000..a68ec7829 Binary files /dev/null and b/docs/sphinx/source/_assets/Feature_Screenshot_Grammar.png differ diff --git a/docs/sphinx/source/_assets/Feature_Screenshot_HTMLExport_01_Index.png b/docs/sphinx/source/_assets/Feature_Screenshot_HTMLExport_01_Index.png new file mode 100644 index 000000000..4ea03339f Binary files /dev/null and b/docs/sphinx/source/_assets/Feature_Screenshot_HTMLExport_01_Index.png differ diff --git a/docs/sphinx/source/_assets/Feature_Screenshot_RSTExport_01_SphinxPDF.png b/docs/sphinx/source/_assets/Feature_Screenshot_RSTExport_01_SphinxPDF.png new file mode 100644 index 000000000..1ebd24d74 Binary files /dev/null and b/docs/sphinx/source/_assets/Feature_Screenshot_RSTExport_01_SphinxPDF.png differ diff --git a/docs/sphinx/source/_assets/Feature_Screenshot_SDoc.png b/docs/sphinx/source/_assets/Feature_Screenshot_SDoc.png new file mode 100644 index 000000000..4c3e77e51 Binary files /dev/null and b/docs/sphinx/source/_assets/Feature_Screenshot_SDoc.png differ diff --git a/docs/sphinx/source/_assets/Feature_Screenshot_SearchScreen_01.png b/docs/sphinx/source/_assets/Feature_Screenshot_SearchScreen_01.png new file mode 100644 index 000000000..549902be5 Binary files /dev/null and b/docs/sphinx/source/_assets/Feature_Screenshot_SearchScreen_01.png differ diff --git a/docs/sphinx/source/_assets/Feature_Screenshot_StatisticsScreen_01.png b/docs/sphinx/source/_assets/Feature_Screenshot_StatisticsScreen_01.png new file mode 100644 index 000000000..b9ff415d9 Binary files /dev/null and b/docs/sphinx/source/_assets/Feature_Screenshot_StatisticsScreen_01.png differ diff --git a/docs/sphinx/source/_assets/Feature_Screenshot_StatisticsScreen_02.png b/docs/sphinx/source/_assets/Feature_Screenshot_StatisticsScreen_02.png new file mode 100644 index 000000000..d88619402 Binary files /dev/null and b/docs/sphinx/source/_assets/Feature_Screenshot_StatisticsScreen_02.png differ diff --git a/docs/sphinx/source/_assets/Feature_Screenshot_StrictDocTOML.png b/docs/sphinx/source/_assets/Feature_Screenshot_StrictDocTOML.png new file mode 100644 index 000000000..fcbe4d4f4 Binary files /dev/null and b/docs/sphinx/source/_assets/Feature_Screenshot_StrictDocTOML.png differ diff --git a/docs/sphinx/source/_assets/Feature_Screenshot_TraceabilityToSource_1.png b/docs/sphinx/source/_assets/Feature_Screenshot_TraceabilityToSource_1.png new file mode 100644 index 000000000..f1b752467 Binary files /dev/null and b/docs/sphinx/source/_assets/Feature_Screenshot_TraceabilityToSource_1.png differ diff --git a/docs/sphinx/source/_assets/Feature_Screenshot_TraceabilityToSource_2.png b/docs/sphinx/source/_assets/Feature_Screenshot_TraceabilityToSource_2.png new file mode 100644 index 000000000..e757a35b3 Binary files /dev/null and b/docs/sphinx/source/_assets/Feature_Screenshot_TraceabilityToSource_2.png differ diff --git a/docs/sphinx/source/_assets/Feature_Screenshot_WebUI.png b/docs/sphinx/source/_assets/Feature_Screenshot_WebUI.png new file mode 100644 index 000000000..6ed0b77d1 Binary files /dev/null and b/docs/sphinx/source/_assets/Feature_Screenshot_WebUI.png differ diff --git a/docs/sphinx/source/_assets/Feature_Screenshot_WebUI_2.png b/docs/sphinx/source/_assets/Feature_Screenshot_WebUI_2.png new file mode 100644 index 000000000..317407ab5 Binary files /dev/null and b/docs/sphinx/source/_assets/Feature_Screenshot_WebUI_2.png differ diff --git a/docs/sphinx/source/_assets/StrictDoc_Workspace-Roadmap.drawio.png b/docs/sphinx/source/_assets/StrictDoc_Workspace-Roadmap.drawio.png index 9e7ed82e4..aa0d2e3ea 100644 Binary files a/docs/sphinx/source/_assets/StrictDoc_Workspace-Roadmap.drawio.png and b/docs/sphinx/source/_assets/StrictDoc_Workspace-Roadmap.drawio.png differ diff --git a/docs/sphinx/source/index.rst b/docs/sphinx/source/index.rst index 8f929ef08..1a8e20c18 100644 --- a/docs/sphinx/source/index.rst +++ b/docs/sphinx/source/index.rst @@ -5,9 +5,10 @@ Welcome to StrictDoc's documentation! :maxdepth: 1 strictdoc_01_user_guide - strictdoc_02_faq - strictdoc_03_release_notes - strictdoc_04_troubleshooting + strictdoc_02_feature_map + strictdoc_03_faq + strictdoc_04_release_notes + strictdoc_05_troubleshooting strictdoc_10_contributing strictdoc_11_developer_guide strictdoc_20_L1_Open_Requirements_Tool diff --git a/docs/sphinx/source/strictdoc_01_user_guide.rst b/docs/sphinx/source/strictdoc_01_user_guide.rst index b7d59a5c3..e2a3d4201 100644 --- a/docs/sphinx/source/strictdoc_01_user_guide.rst +++ b/docs/sphinx/source/strictdoc_01_user_guide.rst @@ -6,6 +6,13 @@ $$$$$$$$$$ Introduction ============ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 27023bf63c414fd998437961c77a0e2e + StrictDoc is software for technical documentation and requirements management. Summary of StrictDoc features: @@ -45,6 +52,13 @@ See also a summary of StrictDoc's existing limitations: :ref:`StrictDoc's limita Contact the developers ---------------------- +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 3ae6491057674be1abf057b7e0d9bf21 + Join us in Discord. Here is the invitation link: https://discord.gg/4BAAME9MmG The author can be also contacted via `email `_. @@ -59,6 +73,13 @@ Examples Hello World ----------- +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - ffbdb80fb21d48adbaeffb782d7994a2 + "Hello World" example of the SDoc text language: .. code-block:: text @@ -122,16 +143,37 @@ Open the URL in the browser and explore the contents of the example. StrictDoc Examples repository ----------------------------- +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - d6bde8e4055b42138d216b48692c8f26 + The `strictdoc-examples `_ repository contains a collection of basic examples. Visit the repository and read its README for details. StrictDoc Templates repository ------------------------------ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 47c2088447d7452ba28962ee220ba63a + The `strictdoc-templates `_ repository contains a growing collection of templates from the industry standards like DO-178C (aviation) and ECSS-E-ST-40C (space). Other examples -------------- +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 2eaa8bfe5a354fcbb704ea7fd94f3a0a + For a more comprehensive example, check the source file of this documentation which is written using StrictDoc: `strictdoc_01_user_guide.sdoc `_. @@ -148,6 +190,13 @@ Installing StrictDoc Requirements ------------ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - e7e4c2982d8e49deaa9b7413a09a4efa + - Python 3.8+ - macOS, Linux or Windows - Command-line terminal program @@ -163,6 +212,13 @@ A terminal program is required to input all the commands outlined in this user g Installing StrictDoc as a Pip package (recommended way) ------------------------------------------------------- +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 872a60c673854cfd909787f2379d88c7 + .. code-block:: text pip install strictdoc @@ -170,6 +226,13 @@ Installing StrictDoc as a Pip package (recommended way) Installing "nightly" StrictDoc as a Pip package ----------------------------------------------- +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 867f22a2767a434586d1ee4f7ee161fb + 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:: @@ -179,6 +242,13 @@ Sometimes, it takes a while before the latest features and fixes reach the stabl Installing StrictDoc into a Docker container -------------------------------------------- +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 32e04944c2a14ead93248ff1ea37a68d + 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. @@ -202,15 +272,31 @@ The documentation resides in ``./docs/output/html``. Installing StrictDoc as a Snap package (not maintained) ------------------------------------------------------- +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 2adfe1bc6be542c3885ca4ea80b8d6e1 + 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``. Running StrictDoc ================= +.. _SECTION-UG-Static-HTML-export: + Static HTML export ------------------ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - c092847abfa04295b63f943c951f24c8 + The easiest way to see the static HTML export feature in action is to run the :ref:`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. @@ -219,9 +305,18 @@ The ``export`` command is the main producer of documentation. The native export strictdoc export --help +.. _SECTION-UG-Web-server: + Web server ---------- +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 1fc9f6f4f84d47439bf6aa3404227ca4 + 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 @@ -239,6 +334,13 @@ The ``server`` command accepts a number of options. To explore the options, run: Security considerations ----------------------- +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 4fa89608f70e4a84a0e4b2930da28bbe + .. 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. @@ -263,6 +365,13 @@ We are committed to continuously enhancing the functionality and security of Str IDE support =========== +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - aad57726976f4882982458de90d168c7 + 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, @@ -300,9 +409,18 @@ implementation for StrictDoc. The StrictDoc LSP is on StrictDoc's long-term roadmap, see `Enhancement: Language Protocol Server for SDoc text language #577 `_. +.. _SECTION-UG-SDoc-syntax: + SDoc syntax =========== +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 556a4f61a4884f3088a743a0717f397f + StrictDoc defines a special syntax for writing specifications documents. This syntax is called SDoc and it's grammar is encoded with the `textX `_ @@ -325,6 +443,13 @@ This documentation is written using StrictDoc. Here is the source file: Document structure ------------------ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 5419c0c9bfcc4922ac5aa79ddb333188 + An SDoc document consists of a ``[DOCUMENT]`` declaration followed by a sequence of nodes: - Lead nodes: ``[TEXT]`` or ``[REQUIREMENT]`` @@ -338,6 +463,13 @@ Each construct is described in more detail below. Strict rule #1: One empty line between all nodes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 2ebd1f2d3c8746a383d71232756c3bd3 + 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 @@ -348,6 +480,13 @@ than one empty line between two nodes will result in an SDoc parsing error. Strict rule #2: No content is allowed outside of SDoc grammar ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 686eb01cf7db44c4bd1edd72ccb02ed0 + StrictDoc's grammar does not allow any content to be written outside of the SDoc grammatical constructs. It is assumed that the critical content shall always be written in form of requirements: @@ -359,6 +498,13 @@ be specified using ``[TEXT]`` nodes. Strict rule #3: No empty strings ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - c01ab5711463497498c91a968179d63c + 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. @@ -405,6 +551,13 @@ Grammar elements Document ~~~~~~~~ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 4b5c6f6fd70e44be8e5be10a38427e77 + The ``[DOCUMENT]`` element must always be present in an SDoc document. It is a root of an SDoc document graph. @@ -454,6 +607,13 @@ by the document's Grammar, i.e. should not be changed. Document configuration options ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 45f3cb9a3da54852a83670af72a4d21b + The ``OPTIONS`` field may have the following attribute fields: .. list-table:: SDoc grammar ``DOCUMENT``-``OPTIONS`` fields @@ -481,11 +641,25 @@ The ``OPTIONS`` field may have the following attribute fields: ENABLE_MID """""""""" +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 196b9e9d857548bebecc698903a593de + See :ref:`Machine identifiers (MID) `. MARKUP """""" +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 19f65eabcd1c4f28a0091133979b5b6e + The ``MARKUP`` option controls which markup renderer will be used. The available options are: ``RST``, ``HTML`` and ``Text``. Default is ``RST``. @@ -493,6 +667,13 @@ The available options are: ``RST``, ``HTML`` and ``Text``. Default is AUTO_LEVELS """"""""""" +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 915b35a9193348108e60968f9b60c1d0 + The ``AUTO_LEVELS`` option controls StrictDoc's system of automatic numbering of the section levels. The available options are: ``On`` / ``Off``. Default is ``On``. @@ -506,6 +687,13 @@ In case of ``Off``, all ``[SECTION].LEVEL`` fields must be populated. REQUIREMENT_STYLE """"""""""""""""" +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 538a721c42824ad6b94a2f54780887ea + The ``REQUIREMENT_STYLE`` option controls whether requirement's elements are displayed inline or as table blocks. The available options are: @@ -525,6 +713,13 @@ Default is ``Inline``. REQUIREMENT_IN_TOC """""""""""""""""" +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - e9e7522f3a094f5ea809f7bae93384d7 + 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``. @@ -539,6 +734,13 @@ Default is ``True``. Text ~~~~ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 4474709783b74b1ca31fa754c712344e + A text node is the most basic document node which is used for normal document text. .. code-block:: text @@ -560,6 +762,13 @@ According to the :ref:`Strict rule #2: No content is allowed outside of SDoc gra Requirement ~~~~~~~~~~~ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - f221cd0c72f846b385ec2f0a9ddd15d5 + The REQUIREMENT element is used for creating requirements, for example technical requirements or project requirements. .. code-block:: text @@ -615,6 +824,13 @@ present. UID ^^^ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 2c3b050a2cd0444fb8948bb6adcb7085 + Unique identifier of the requirement. **Observation:** Some documents do not use unique identifiers which makes it @@ -643,18 +859,39 @@ typical conventions for naming UIDs: Level ^^^^^ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - bc3355748bb34f5da11336f5f1a72739 + Also a ``[REQUIREMENT]`` can have no section level attached to it. To enable this behavior, the field ``LEVEL`` has to be set to ``None``. Status ^^^^^^ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - ab255589592043e2a6a86b74a9441d31 + Defines the current status of the ``[REQUIREMENT]``, e.g. ``Draft``, ``Active``, ``Deleted``. Tags ^^^^ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - d7c2d72f849b413cb312d44813d25d5a + 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. @@ -664,6 +901,13 @@ supported. Relations (previously REFS) ^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - c0c9c15d57e742ed80f12b8895f01de0 + The ``RELATIONS`` field is used to connect requirements to each other: .. code-block:: text @@ -712,6 +956,13 @@ requirements connected with a reference have ``UID`` defined. Requirement relation roles """""""""""""""""""""""""" +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - a54f41576b2d40df92041862bef13600 + A requirement relation can be specialized with a role. The role must be registered in the document grammar, see :ref:`Relations `. .. code-block:: @@ -744,6 +995,13 @@ In this example REQ-1 is the parent of REQ-2 and REQ-2 refines REQ-1. Title ^^^^^ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - f5f9008f417e40aa8acd9da18ccd89d1 + The title of the requirement. Every requirement should have its ``TITLE`` field specified. @@ -763,12 +1021,26 @@ titles but some documents only use statements without title in which case their Statement ^^^^^^^^^ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - cea069906c2e4329bea0d97744984ba8 + The statement of the requirement. The field can be single-line or multiline. Every requirement shall have its ``STATEMENT`` field specified. Rationale ^^^^^^^^^ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 7e63bdbce418401da8eb5aa607fd8fc2 + 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. @@ -787,6 +1059,13 @@ or multiline. Comment ^^^^^^^ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 3928acde165b4505943154199ecd739a + A requirement can have one or more comments explaining the requirement. The comments can be single-line or multiline. @@ -812,6 +1091,13 @@ comments can be single-line or multiline. Section ~~~~~~~ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 14e5fea31b1c41bf8c743f18e51053e0 + 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. @@ -842,6 +1128,13 @@ requirements into logical groups. It is equivalent to the use of ``#``, ``##``, Nesting sections ^^^^^^^^^^^^^^^^ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - fa700a9b975f493ba7ec2fd0a7b44bbe + Sections can be nested within each other. .. code-block:: text @@ -871,6 +1164,13 @@ sections will have their titles numbered accordingly: ``1 Chapter`` and Section without a level ^^^^^^^^^^^^^^^^^^^^^^^ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 094425a33e8941d9a0016b4ed714c664 + A section can have no level attached to it. To enable this behavior, the field ``LEVEL`` has to be set to ``None``. @@ -907,6 +1207,13 @@ are set to ``LEVEL: None`` by StrictDoc automatically. Composing documents from other documents ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 6ed881a7cb8949cab3d1a1836846b716 + .. note:: The composable documents is an early feature with only 50%+ of the implementation complete. See `Epic: UI: Composable documents `_. @@ -985,6 +1292,13 @@ Which will resolve to the following document after inclusion: Composite requirement ~~~~~~~~~~~~~~~~~~~~~ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - ce69fe89236a4bcfa104a640def4b64a + .. 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. @@ -1025,6 +1339,13 @@ elements should do the job. Machine identifiers (MID) ------------------------- +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 7fe2832d60014259a8d67a09f1db102a + 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:: @@ -1064,6 +1385,13 @@ For larger projects, particularly those with extended maintenance cycles, we str Custom grammars --------------- +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 4c2244d6affb4653844f730e1de88266 + **Observation:** Different industries have their own types of requirements documents with specialized meta information. Examples: ``ASIL`` in the automotive industry or @@ -1138,6 +1466,13 @@ grammar. Supported field types ~~~~~~~~~~~~~~~~~~~~~ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - a437c871dc3d46dba80460d5c8c22cf6 + The supported field types are: .. list-table:: SDoc grammar field types @@ -1231,6 +1566,13 @@ Example: Reserved fields ~~~~~~~~~~~~~~~ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 4d69fa95bd974d859973dbb34679a7c4 + 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: @@ -1269,6 +1611,13 @@ is a fixed set of reserved fields that StrictDoc uses for the presentation of th Relations ~~~~~~~~~ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 012b0350547a48fc9ab3fbd6d9b5d502 + The custom grammar configuration includes the optional ``RELATION:`` section which specifies the relations a given document supports. .. code-block:: @@ -1301,6 +1650,13 @@ The default grammar relations, when a custom grammar is not specified, are ``Par Relation roles ^^^^^^^^^^^^^^ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 01b8aa59963b42518d98c4e6b5e3259b + 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:: @@ -1324,6 +1680,13 @@ With this grammar, StrictDoc will only allow creating requirements that have Par Parent vs Child relations ^^^^^^^^^^^^^^^^^^^^^^^^^ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - b119e614781044eab641e20eaec872e5 + **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. @@ -1387,6 +1750,13 @@ Both examples above involve activity called Tailoring when an intermediate docum Importing grammar from grammar file ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - df106206da0e446e87021fbf711fdb65 + 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: @@ -1431,11 +1801,25 @@ When a ``[GRAMMAR]`` is declared with an ``IMPORT_FROM_FILE`` line, the grammar Links ----- +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 6ce1010a003146ec9e3e8d77ee89a082 + StrictDoc supports creating inline links to document sections, anchors, requirements and custom grammar elements. Links ~~~~~ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 8b07c82f462348a58c3ab81be4db753d + 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: ]``. @@ -1449,6 +1833,13 @@ The following link references a section: :ref:`Links Anchors ~~~~~~~ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 294d6a0e96424dc8a93d6502c43e8501 + The ``[ANCHOR: , ]`` tag creates an anchor that can be referenced from other pages using ``[LINK ]``. Example: @@ -1460,13 +1851,29 @@ Note: ``ANCHOR`` is a block-level tag. It has to be placed in the beginning of a Anchor example ^^^^^^^^^^^^^^ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - ba71ef8f24b342178b28e87b7609b8d7 + This section contains an anchor named ``Anchor ABC``. .. _ANCHOR-EXAMPLE: +.. _SECTION-UG-Search-and-filtering: + Search and filtering ==================== +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - de584af947a445e5bcc782bab6a93baf + StrictDoc supports search and filtering of document content. However, this feature has not been extensively tested and is hidden behind a feature flag. To activate it, enable the corresponding setting in the ``strictdoc.toml`` configuration file: .. code-block:: @@ -1482,6 +1889,13 @@ The web interface includes the Search screen, designed for conducting queries ag Query engine ------------ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 29ffc3e91d8045589b0837f647286128 + The syntax of the search query is inspired by Python, utilizing a fixed grammar that converts search queries into corresponding Python expressions. Important rules: @@ -1518,6 +1932,13 @@ Important rules: Filtering content ----------------- +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - d52d86750ad54ce1b3263ebb092451c0 + 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. @@ -1531,6 +1952,13 @@ Example: Markup ====== +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - a3d675f38a1341548722239e994e55e1 + The Restructured Text (reST) markup is the default markup supported by StrictDoc. The reST markup can be written inside all StrictDoc's text blocks, such as ``STATEMENT``, ``COMMENT``, ``RATIONALE``, etc. @@ -1545,6 +1973,13 @@ The support of Tex and HTML is planned. Images ------ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - e87ffdf6195c481cb39bc3d1ec29eca6 + To insert an image into a document, create a folder named ``_assets`` alongside your document and then place the image file into it. This is the example of how images are included using the reST syntax: @@ -1563,6 +1998,13 @@ This is the example of how images are included using the reST syntax: Mathjax support --------------- +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - abdf406fe10847929dd7cb12a030456f + StrictDoc can include the `MathJax `_ Javascript library to all of the document templates. To activate MathJax, edit the ``strictdoc.toml`` config file in the root of your repository with documentation content. .. code-block:: @@ -1598,6 +2040,13 @@ Export formats HTML documentation tree by StrictDoc ------------------------------------ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - a6bfffddf89045a1a7ecf55c9681fe14 + This is a default export option supported by StrictDoc. The following command creates an HTML export: @@ -1616,6 +2065,13 @@ StrictDoc does not detect .sdoc files in the output folder. This is based on the Standalone HTML pages ~~~~~~~~~~~~~~~~~~~~~ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 5674bfd50f31420baf56625d79d1ebff + 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: @@ -1631,9 +2087,18 @@ The generated document are self-contained HTML pages that can be shared via email as single files. This option might be especially useful if you work with a single document instead of a documentation tree with multiple documents. +.. _SECTION-UG-HTML-export-via-Sphinx: + HTML export via Sphinx ---------------------- +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - bf8160f43703418db306785c48463123 + The following command creates an RST export: .. code-block:: text @@ -1653,9 +2118,18 @@ The created RST files can be copied to a project created using Sphinx, see is generated this way, see the Invoke task: `invoke sphinx `_. +.. _SECTION-UG-PDF-export-via-Sphinx-LaTeX: + PDF export via Sphinx/LaTeX --------------------------- +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 58595abe6ff148afbb45e2b6adc25110 + The following command creates an RST export: @@ -1679,6 +2153,13 @@ is generated this way, see the Invoke task: JSON ---- +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 4d956edcd00846a98f59778dd7de9257 + The following command creates a JSON export: .. code-block:: @@ -1697,6 +2178,13 @@ Manage project tree Automatic assignment of requirements UID ---------------------------------------- +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - ed367ed0bc284d4d9318bf6c844c3e3e + To assign requirement UIDs automatically: .. code-block:: @@ -1730,6 +2218,13 @@ A section-level requirement mask: Traceability between requirements and source code ================================================= +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 4398b17f61ad4dd290e72d7888597f48 + **Note:** This feature is experimental, the documentation is incomplete. StrictDoc allows connecting requirements to source code files in two ways: @@ -1767,6 +2262,13 @@ requirements-to-source-code traceability. Language-aware parsing of source code ------------------------------------- +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 07bfe045a4934dd29d97fdb8ac567b7c + For parsing source code and calculating traceability to requirements, StrictDoc uses a general parser that is agnostic of specific programming languages and their constructs, such as classes or functions. However, for languages with these constructs, establishing traceability to them can simplify the tracing process. As an experimental option, StrictDoc supports parsing source files of selected programming languages (currently Python and C) to recognize language syntax, primarily enabling traceability of functions (in Python, C, and others) and classes (in Python, C++, and others) to requirements. @@ -1787,6 +2289,13 @@ Currently, only Python and C parsers are implemented. Upcoming implementations i Linking source code to requirements ----------------------------------- +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - c787c538cc0a422fb2898b525ec1006d + To connect a source file to a requirement, a dedicated ``@relation`` marker must be added to the source file. Several marker types are supported, depending on the programming language. For example, the ``scope=class`` option is available for Python files but not for C files, as C does not support classes. .. note:: @@ -1865,6 +2374,13 @@ or Linking requirements to source code ----------------------------------- +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 1c06fb7b90114633801d177459f482b5 + The linking of requirements to source files is arranged with a special RELATION type ``File``. .. note:: @@ -1929,9 +2445,18 @@ The linking of requirements to source files is arranged with a special RELATION VALUE: file.py CLASS: Foo +.. _SECTION-UG-ReqIF-support: + ReqIF support ============= +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - b510d9337e604bfda366f2ec605f4c88 + StrictDoc has an initial support of exporting to and importing from the ReqIF format. @@ -1954,6 +2479,13 @@ Planned formats: Import flow (ReqIF -> SDoc) --------------------------- +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 079ed6d7ec3f4040b59efce7ccd37267 + .. code-block:: text strictdoc import reqif sdoc input.reqif output.sdoc @@ -1972,6 +2504,13 @@ The command does the following: Export flow (SDoc -> ReqIF) --------------------------- +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 94641cac6b9748bfa2de8648ff197584 + .. code-block:: text strictdoc export --formats=reqif-sdoc %S/input.sdoc @@ -1990,6 +2529,13 @@ The command does the following: ReqIF options ------------- +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 57dd1fb10ba64e2f8e0b75baf772b634 + 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. @@ -2014,6 +2560,13 @@ All options can be also specified in a project's TOML file as follows: ReqIF implementation details ---------------------------- +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - edd5c3bf902e48deaee3248d12087a75 + 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 @@ -2040,6 +2593,13 @@ documentation. Excel support ============= +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 65c1657a8fb04179960fca4ece265b18 + 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 @@ -2052,6 +2612,13 @@ Note: A roundtrip "SDoc -> Excel -> SDoc" is not yet supported. Import flow (Excel XLS -> SDoc) ------------------------------- +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - b01355b5a6d54409a0c7a684376a5278 + .. code-block:: text strictdoc import excel basic input.xls output.sdoc @@ -2066,6 +2633,13 @@ The command does the following: Export flow (SDoc -> Excel XLSX) -------------------------------- +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 14161a9fa81d427f8a5a21367359339e + .. code-block:: text strictdoc export --formats=excel --output-dir=Output input.sdoc @@ -2099,6 +2673,13 @@ Options Project-level options --------------------- +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 6449098df878484fbe8aed8a8b0e9a97 + 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. @@ -2106,6 +2687,13 @@ For example, ``strictdoc export .`` will make StrictDoc recognize the config fil Project title ~~~~~~~~~~~~~ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 12501275599f4d7a954892e1a56778b9 + This option specifies a project title. .. code-block:: @@ -2116,6 +2704,13 @@ This option specifies a project title. Path to assets ~~~~~~~~~~~~~~ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 7d1102cda98c4ea18c6e646b73511097 + 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. @@ -2130,6 +2725,13 @@ The ``html_assets_strictdoc_dir`` allows changing the assets folder name: Path to cache dir ~~~~~~~~~~~~~~~~~ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - e94e9762cc0e4e1eafe57d0d9e03eb5b + StrictDoc uses caching when reading and writing artifacts. By default, all caches are written to the system's temporary directory (``$TMPDIR``). The ``cache_dir`` option in the configuration file allows specifying a custom directory, such as ``./output/build``. This setting can help make caching artifacts visible alongside documentation artifacts. @@ -2144,6 +2746,13 @@ See :ref:`Caching artifacts ` for an overview of h Path to source root ~~~~~~~~~~~~~~~~~~~ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - be42ecf5c8a84fc3bca0b73ea50647de + 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:: @@ -2161,6 +2770,13 @@ The ``source_root_path`` option supports relative paths, e.g. ``../source_root/` Include/exclude document paths ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 27e5981c451d4ad4938ab622e3cf0be2 + 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. @@ -2201,6 +2817,13 @@ The behavior of wildcard symbols ``*`` and ``**`` is as follows: Include/exclude source files paths ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 3908f98fab5c47668ba752d0e93033ab + 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 @@ -2226,6 +2849,13 @@ The behavior of the wildcards is the same as for the ``include_doc_paths/exclude Selecting features ~~~~~~~~~~~~~~~~~~ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - f43d8170c44b4d70ada2816fe71caf07 + 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. @@ -2260,6 +2890,13 @@ See :ref:`Experimental features ` where the exper Enable all features ^^^^^^^^^^^^^^^^^^^ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - d33880e1740d4d0892852cc8c425f66f + To select all available features, stable and experimental, specify ``ALL_FEATURES``. .. code-block:: @@ -2279,6 +2916,13 @@ If ``ALL_FEATURES`` is present, all features are activated, regardless of any ot Disable all features ^^^^^^^^^^^^^^^^^^^^ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 9cf2ac683b7a4e939286146ef00631c1 + To disable all features, specify the ``features`` option but leave it empty: .. code-block:: yaml @@ -2295,6 +2939,13 @@ Server configuration Host and port ^^^^^^^^^^^^^ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 9943131c688c400b99e2db9ec4854480 + By default, StrictDoc runs the server on ``127.0.0.1:5111``. Use the ``[server]`` section to configure the host and port as follows. @@ -2314,6 +2965,13 @@ Command-line interface options Project title ~~~~~~~~~~~~~ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 81d8e1beb5904cb78dfde2712ff3f311 + By default, StrictDoc generates a project tree with a project title "Untitled Project". To specify the project title use the option ``--project-title``. @@ -2325,6 +2983,13 @@ By default, StrictDoc generates a project tree with a project title Parallelization ~~~~~~~~~~~~~~~ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - f8ff07833ff942dfabdad2412350cd0c + 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 @@ -2347,6 +3012,13 @@ all export options and is disabled with this option as well. Python API ========== +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 4504bffd6ced4aa78848ee9e03fdd4b7 + 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 :ref:`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. @@ -2366,6 +3038,13 @@ For any custom Python API request, for example, a need to do a more advanced dat Portability considerations ========================== +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - e15260727be84ce394386a4f95c627ae + .. 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. @@ -2387,6 +3066,13 @@ The following is a list of features that are considered less portable when it co Experimental features ===================== +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 5b400736aec54789b2ed3ebcffcf961e + 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. @@ -2398,6 +3084,13 @@ See also :ref:`Selecting features ` for general instruc Project statistics screen ------------------------- +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 2fefc893de83432fa852886cc3a05fea + 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. @@ -2413,9 +3106,49 @@ 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. +.. _SECTION-UG-Diff-changelog-screen: + +Diff/changelog screen +--------------------- + +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 131a7392a33f4225a62539dd173a920b + +The "Git Diff/Changelog" experimental feature in StrictDoc allows users to track changes between different versions of requirement documents. This feature provides a visual diff by highlighting what content has been added, removed, or modified within the SDoc files, using a style similar to Git diffs. It helps in maintaining version history, ensuring that changes are traceable, and supports auditing by showing how requirements evolve over time. + +To activate the Diff/Changelog screen, add/edit the strictdoc.toml config file in the root of your repository with documentation content. + +.. code:: toml + + [project] + title = "My project" + + features = [ + "DIFF" + ] + +.. admonition:: Robust MID-based change tracking + :class: note + + For optimal results when using the Diff/Changelog feature in a StrictDoc-based project, it is strongly recommended to enable Machine Identifiers (MIDs) for all project artifacts, such as TEXT, REQUIREMENT, etc. + Without MIDs, StrictDoc cannot ensure accurate change tracking. If a node lacks an MID, StrictDoc is unable to reliably detect whether it has been modified or relocated in subsequent versions of the documentation tree. For further details, refer to :ref:`Machine identifiers (MID) `. + +.. _SECTION-UG-HTML2PDF-document-generator: + HTML2PDF document generator --------------------------- +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 6e610b9a381f4b5d9d26004dd286e001 + StrictDoc offers an experimental feature for converting HTML documents into PDF files. This feature aims to deliver a good PDF printing experience without the necessity of installing more sophisticated printing systems like LaTeX. There are three methods of PDF printing available: @@ -2450,6 +3183,13 @@ This feature is not enabled by default because the implementation has not been c Mermaid diagramming and charting tool ------------------------------------- +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 6a4e4467a5c0451ea8291fd94309d525 + The Mermaid tool allows to create diagrams inside of StrictDoc/RST markup as follows: .. code:: @@ -2486,6 +3226,13 @@ This feature is not enabled by default because it has not received enough testin Shadow features --------------- +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 38fa0af0d01e479ba7f5be046bae02eb + 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. @@ -2504,6 +3251,13 @@ StrictDoc's limitations Limitations of RST support by StrictDoc --------------------------------------- +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - f7b039831f4e4c1ea19b45efe71c5365 + 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 `_. .. _SDOC_UG_LIMIT_WEB: @@ -2511,6 +3265,13 @@ StrictDoc uses Docutils for rendering RST to HTML, not Sphinx. The implication i Limitations of web user interface --------------------------------- +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 911c454331634018b8de24186ae8e742 + The existing implementation of the web user interface is alpha-quality and incomplete. The user interface and the underlying backend implementation are not yet autonomous from the command-line workflow. A user still has to access the command line to run the server and commit the documents to Git manually. The currently supported workflow for the ``server`` command must be hybrid: @@ -2534,6 +3295,13 @@ The following essential features are still missing and will be worked on in the Concurrent use of web user interface ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - bdee3bde500a40878b70be44f113cf2c + 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. @@ -2541,6 +3309,13 @@ The measures for handling concurrent use are planned but have been not implement Known issues ============ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 9282f2d7218a4f2e967b6df45b0347ab + This section documents some known issues and non-obvious implementation details. .. _SDOC_IMPL_2: @@ -2548,6 +3323,13 @@ This section documents some known issues and non-obvious implementation details. Running out of semaphores on macOS ---------------------------------- +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - ec83d51626ee4e0cbb75c500ee306b06 + This an edge case on macOS: Python crashes in the Parallelizer class when creating an output queue: @@ -2576,6 +3358,13 @@ Appendices FREETEXT-TEXT migration (June 2024) ----------------------------------- +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 2509cce7ee634c7a8878c5e1094b83f2 + A new grammar node called ``TEXT`` has been introduced in the SDoc grammar, replacing the ``FREETEXT`` node as a more powerful feature. The reasons for the migration: @@ -2602,6 +3391,13 @@ There are three important consequences of this migration. How to migrate from FREETEXT to TEXT ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 5d2f033604824264b1cc05840997c6b8 + The backward compatibility is preserved. The users can still create SDoc documents with ``FREETEXT`` but internally the free text nodes will be anyway converted to ``TEXT`` nodes, and the FREETEXT node no longer exist in the SDoc document model. The users are encouraged to perform the migration as follows. diff --git a/docs/sphinx/source/strictdoc_02_feature_map.rst b/docs/sphinx/source/strictdoc_02_feature_map.rst new file mode 100644 index 000000000..ea9084a7f --- /dev/null +++ b/docs/sphinx/source/strictdoc_02_feature_map.rst @@ -0,0 +1,574 @@ +.. _SDOC_FEATURE_MAP: + +StrictDoc Feature Map +$$$$$$$$$$$$$$$$$$$$$ + +This document provides a comprehensive overview of all available features in StrictDoc from the user's perspective. It includes descriptions and relevant screenshots to illustrate each feature's functionality. Each entry is linked to additional documentation, such as the :ref:`User Guide `, offering further details, usage instructions, and examples to help users understand and effectively utilize StrictDoc’s capabilities. + +.. _SECTION-FM-SDoc-text-markup: + +SDoc text markup +================ + +Definition +---------- + +.. _SDOC-FEAT-1: + +SDoc text markup +~~~~~~~~~~~~~~~~ + +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 4c40803dd0f04af88fd722ba6b732270 + * - **UID:** + - SDOC-FEAT-1 + * - **STATUS:** + - Stable + +The SDoc markup language is a hybrid format inspired by TOML, YAML, ASN.1, and HTML/XML, designed specifically for structuring technical documents with large volumes of requirements. It aims to encode documents that span up to several hundred or even a few thousand A4-printed pages, while keeping the markup noise minimal to maintain readability. The format supports both shallow and deeply nested document structures, accommodating up to 9-10 levels of chapter nesting, and allows for multiple meta-information fields around each requirement. + +**DOCUMENTATION:** + +- :ref:`SDoc syntax ` + +Use case +-------- + +The main use case for SDoc is to model a structure of a technical document that consists of tens and hundreds of technical requirements. The following high-level requirements for the markup are therefore relevant: + +- Encode documents of reasonable size (up to several hundreds or few thousands of A4-printed pages). +- Visualize large blocks of requirements text without too much markup noise. +- Support documents with nested (2-4 levels) or deeply nested structure (detailed technical specifications with up to 9-10 levels of chapter nesting). +- Support multiple fields for requirement meta information which makes a requirement look like "a text with some meta information around it". + +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. + +Inspirations +------------ + +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. + +**TOML: Square bracket syntax** + +From TOML, StrictDoc borrowed the ``[]`` bracket syntax to create the ``[REQUIREMENT]``, ``[SECTION]`` and other blocks but uses the YAML-like syntax for these blocks' fields, for example: + +.. code-block:: + + [REQUIREMENT] + TITLE: Requirement ABC + STATEMENT: The system A shall do B when C. + +**TOML/YAML: Arrays/dictionaries** + +StrictDoc has a rudimentary support of arrays and dictionaries. For example, the syntax for defining the document's ``[GRAMMAR]`` resembles what would look like an array of records in YAML: + +.. code-block:: + + [GRAMMAR] + ELEMENTS: + - TAG: REQUIREMENT + FIELDS: + - TITLE: UID + TYPE: String + REQUIRED: True + - TITLE: LEVEL + TYPE: String + REQUIRED: False + +**Capitalization of reserved keywords from ASN.1** + +From ASN.1, StrictDoc borrows the idea of having all reserved fields capitalized. This helps to visually distinguish between the grammar content and user content. + +**Nested sections** + +From HTML, the idea of opening and closing tags is taken to avoid any nesting that would otherwise be required to support the deeply nested documents with up to 6 or 8 levels, e.g., 1.1.1.1.1.1.1... + +.. code-block:: + + [SECTION] + TITLE: Section 1 + + [SECTION] + TITLE: Section 1.1 + + ... + + [/SECTION] + + [/SECTION] + +Taking HTML or XML as-is didn't seem like a good option because of the heavy visual noise that is produced around the actual content by the surrounding tags. + +**Multiline strings** + +The support of multiline strings is arranged by a custom solution which helps to avoid any nesting of multiline text as well as to visually indicate the start and end parts of the multiline string in a visually unambiguous way. This is how the multiline string is declared: + +.. code-block:: + + [REQUIREMENT] + TITLE: Requirement ABC + STATEMENT: >>> + The multiline requirement statement + without any nesting. + >>> + +**Discarded options** + +Taking TOML or YAML as-is didn't seem like a good option because these formats are designed to be used for configuration files or data serialization and not for large documents with hundreds of requirements. The most obvious problems for reusing either of TOML or YAML directly would have been with encoding the deeply nested documents and supporting readable and non-nested multiline strings. + +Screenshots +----------- + +.. image:: _assets/Feature_Screenshot_SDoc.png + :alt: SDoc markup + :class: image + :width: 100% + +HTML export +=========== + +Definition +---------- + +.. _SDOC-FEAT-2: + +StrictDoc HTML export +~~~~~~~~~~~~~~~~~~~~~ + +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 8e6604c8b27b450cbd21c12dc8572291 + * - **UID:** + - SDOC-FEAT-2 + +StrictDoc's static HTML export feature allows users to generate comprehensive documentation from .sdoc files into a well-structured HTML format. It leverages an efficient in-memory representation of document trees, supporting large-scale documents with thousands of requirements while maintaining decent performance. + +The HTML output preserves the hierarchy of requirements, including parent-child relationships, to facilitate traceability and coverage analysis. + +Additionally, StrictDoc's incremental generation mechanism ensures quick updates by only regenerating modified documents, enabling efficient handling of extensive requirements specifications. + +**DOCUMENTATION:** + +- :ref:`Static HTML export ` + +Screenshots +----------- + +.. image:: _assets/Feature_Screenshot_HTMLExport_01_Index.png + :alt: StrictDoc HTML export – Project tree + :class: image + :width: 100% + +Web-based graphical user interface +================================== + +Definition +---------- + +.. _SDOC-FEAT-3: + +StrictDoc web-based graphical user interface +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 2c1cde585d5944b5b7b5a0d5f72a98ed + * - **UID:** + - SDOC-FEAT-3 + * - **STATUS:** + - Stable + +StrictDoc features an editable web interface that enables users to view and modify requirements directly within their browser. This interface provides a user-friendly way to interact with .sdoc files, allowing real-time editing of documents and requirements. Changes made through the web interface are automatically saved back to the original text files, ensuring synchronization between the user interface and the underlying document structure. The web interface also supports visualization of requirement hierarchies and relationships, making it easier to manage complex documents with multiple nested levels and linked requirements. + +**DOCUMENTATION:** + +- :ref:`Web server ` +- :ref:`Limitations of web user interface ` + +Screenshots +----------- + +.. image:: _assets/Feature_Screenshot_WebUI.png + :alt: StrictDoc web interface + :class: image + :width: 100% + +.. image:: _assets/Feature_Screenshot_WebUI_2.png + :alt: StrictDoc web interface + :class: image + :width: 100% + +Traceability between requirements and source code +================================================= + +Definition +---------- + +.. _SDOC-FEAT-4: + +Traceability between requirements and source code +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - e14eee106ea443e598378e55401914dc + * - **UID:** + - SDOC-FEAT-4 + +StrictDoc supports traceability between requirements and source code, enabling the creation of links from requirements specified in .sdoc files to relevant source code files. This feature ensures that each requirement is adequately addressed in the implementation by associating it with corresponding segments of the codebase. Traceability links are defined using custom references, allowing teams to track which parts of the code fulfill specific requirements. This capability is essential for compliance, validation, and maintaining consistency between documentation and actual implementation. These connections can be visualized in the generated HTML exports, providing a clear and navigable overview of the relationship between requirements and the codebase​. + +**DOCUMENTATION:** + +- :ref:`Traceability between requirements and source code ` + +Screenshots +----------- + +.. image:: _assets/Feature_Screenshot_TraceabilityToSource_1.png + :alt: Traceability to source 1 + :class: image + :width: 100% + +.. image:: _assets/Feature_Screenshot_TraceabilityToSource_2.png + :alt: Traceability to source 2 + :class: image + :width: 100% + +Document grammar +================ + +Definition +---------- + +.. _SDOC-FEAT-5: + +Custom document grammars +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 0bfcb6144dde487791d4f01164dd7e7c + * - **UID:** + - SDOC-FEAT-5 + +The "Document grammar" feature allows users to extend the default grammar to fit specific project needs, particularly useful for industries with specialized requirements documentation, such as automotive or aerospace. This feature supports defining custom fields like "PRIORITY," "VERIFICATION," or domain-specific tags like "ASIL" for automotive safety standards. Custom grammars are declared at the document level using the ``[GRAMMAR]`` directive, enabling users to specify custom fields and their data types, such as ``String``, ``SingleChoice``, ``MultipleChoice``. These fields can be marked as mandatory, ensuring consistency across requirements documents. + +**DOCUMENTATION:** + +- :ref:`Custom grammars ` + +Screenshots +----------- + +.. image:: _assets/Feature_Screenshot_Grammar.png + :alt: Document grammar + :class: image + :width: 100% + +Composable documents +==================== + +Definition +---------- + +.. _SDOC-FEAT-6: + +Composable documents +~~~~~~~~~~~~~~~~~~~~ + +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - e7b2d61545eb414f97345ecac25c52cc + * - **UID:** + - SDOC-FEAT-6 + +The "Composable Documents" feature in StrictDoc enables users to create composite documents made up of smaller, independent SDoc documents. This modular approach allows each document fragment to be managed separately, which is particularly useful when dealing with large, complex requirements documents. + +**DOCUMENTATION:** + +- :ref:`Composing documents from other documents ` + +Export to RST +============= + +Definition +---------- + +.. _SDOC-FEAT-8: + +Export to RST +~~~~~~~~~~~~~ + +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - dd686a557c3e4e50ba89538a74d39383 + * - **UID:** + - SDOC-FEAT-8 + * - **STATUS:** + - Stable + +The "Export to RST" feature in StrictDoc allows users to convert their SDoc documentation into reStructuredText (RST) format, which is compatible with Sphinx documentation generator. This process enables a two-stage conversion workflow where SDoc documents can first be exported to RST and then further processed by Sphinx to generate HTML websites, PDF documents, or other formats. This feature is particularly useful for users who already have a Sphinx-based documentation pipeline, as it integrates StrictDoc’s requirements management capabilities with Sphinx. + +**DOCUMENTATION:** + +- :ref:`HTML export via Sphinx ` +- :ref:`PDF export via Sphinx/LaTeX ` +- :ref:`Limitations of RST support by StrictDoc ` + +Screenshots +----------- + +**Export to RST and PDF using Sphinx/LaTeX** + +.. image:: _assets/Feature_Screenshot_RSTExport_01_SphinxPDF.png + :alt: StrictDoc HTML export – Project tree + :class: image + :width: 100% + +Export to PDF +============= + +Definition +---------- + +.. _SDOC-FEAT-10: + +Export to PDF +~~~~~~~~~~~~~ + +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 5be4f35be2eb49faae7c33b5a2d83251 + * - **UID:** + - SDOC-FEAT-10 + * - **STATUS:** + - Experimental + +The HTML2PDF feature in StrictDoc enables web-based printing to PDF by leveraging ChromeDriver and Google Chrome. This approach uses the Selenium Python library to automate the printing of HTML content directly to PDF format, ensuring that the final document mirrors the exact HTML content rendered in the browser. + +The feature allows the user to export content to PDF via a web interface or through a command-line interface. This ensures that the output closely resembles the web page, with no need for additional formatting or adjustments to the content. + +**DOCUMENTATION:** + +- :ref:`HTML2PDF document generator ` + +Screenshots +----------- + +Query engine and search screen +============================== + +Definition +---------- + +.. _SDOC-FEAT-7: + +Query engine and search screen +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 9c1e6cb601294891bcaae2b8c9042c59 + * - **UID:** + - SDOC-FEAT-7 + * - **STATUS:** + - Experimental + +The "Query Engine and Search Screen" feature in StrictDoc offers tools for searching and filtering requirements within documents. It uses a Python-inspired syntax to perform complex queries on the document tree, allowing users to find specific sections or requirements based on attributes like titles, parent-child relationships, or custom fields. The search screen is integrated into the web interface, where users can craft queries with logical operators (e.g., AND, OR) and attribute filters (e.g., ``node.is_requirement``). + +**DOCUMENTATION:** + +- :ref:`Search and filtering ` + +Screenshots +----------- + +.. image:: _assets/Feature_Screenshot_SearchScreen_01.png + :alt: StrictDoc Search Screen + :class: image + :width: 100% + +Project statistics +================== + +Definition +---------- + +.. _SDOC-FEAT-11: + +Project Statistics +~~~~~~~~~~~~~~~~~~ + +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 2dd0b514a24f43a287a4096d0be0af58 + * - **UID:** + - SDOC-FEAT-11 + * - **STATUS:** + - Experimental + +The "Project Statistics" feature in StrictDoc provides insights into the overall status and details of a documentation project. It offers statistical data that can include information about requirements, document structure, and coverage. + +**DOCUMENTATION:** + +- :ref:`Project statistics screen ` + +Screenshots +----------- + +.. image:: _assets/Feature_Screenshot_StatisticsScreen_01.png + :alt: Project statistics + :class: image + :width: 100% + + +.. image:: _assets/Feature_Screenshot_StatisticsScreen_02.png + :alt: Project statistics + :class: image + :width: 100% + +Documentation diff/changelog +============================ + +Definition +---------- + +.. _SDOC-FEAT-12: + +Documentation diff/changelog +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - e9da42f8e39b438a8e8eada16b280706 + * - **UID:** + - SDOC-FEAT-12 + * - **STATUS:** + - Experimental + +The "Documentation diff/changelog" feature in StrictDoc allows users to track and compare changes made between different versions of project documentation. This feature can highlight modifications at a granular level, such as added, deleted, or altered content within the document. + +**DOCUMENTATION:** + +- :ref:`Diff/changelog screen ` + +Screenshots +----------- + +.. image:: _assets/Feature_Screenshot_DiffChangelog_1.png + :alt: StrictDoc Diff/Changelog 1 + :class: image + :width: 100% + +.. image:: _assets/Feature_Screenshot_DiffChangelog_2.png + :alt: StrictDoc Diff/Changelog 2 + :class: image + :width: 100% + +ReqIF support +============= + +Definition +---------- + +.. _SDOC-FEAT-13: + +ReqIF support +~~~~~~~~~~~~~ + +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 2845463f977d4b51ac788c2fc9cbd894 + * - **UID:** + - SDOC-FEAT-13 + * - **STATUS:** + - Experimental + +The ReqIF support feature in StrictDoc allows for both importing and exporting to the ReqIF format, facilitating interoperability with other requirements management tools. + +ReqIF is a widely used XML-based standard for requirements data exchange. The import flow allows ReqIF files to be converted into SDoc documents, while the export flow enables SDoc content to be converted back into ReqIF format. + +The implementation of ReqIF support is tool-specific due to the flexibility of the ReqIF standard. Different tools may structure and name their fields differently, which means the export/import workflows may require adjustments depending on the tools involved. StrictDoc provides its own model for converting between ReqIF and SDoc, making it adaptable for specific use cases while striving for compatibility with the ReqIF format recommended by the ReqIF Implementation Guide​. + +**DOCUMENTATION:** + +- :ref:`ReqIF support ` + +Project configuration +===================== + +Definition +---------- + +.. _SDOC-FEAT-9: + +Project configuration +~~~~~~~~~~~~~~~~~~~~~ + +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 8fc72d79bfe940aba2cf041e263b92df + * - **UID:** + - SDOC-FEAT-9 + +The "strictdoc.toml" file is a project-level configuration file used in StrictDoc to manage various project settings. This configuration file allows customization for features such as selected functionalities, document paths, source file paths, etc. + +Key options in the "strictdoc.toml" file include: + +- Project title: Defines a project title. +- Feature selection: Selects additional features to activate or deactivate, such as traceability features or experimental tools. +- Paths customization: cache dir, asset dir, document include/exclude paths, source file include/exclude paths, etc. + +This configuration ensures that StrictDoc works according to the specific needs of a given project, making it more flexible and adaptable​. + +**DOCUMENTATION:** + +- :ref:`Project-level options ` + +Screenshots +----------- + +.. image:: _assets/Feature_Screenshot_StrictDocTOML.png + :alt: StrictDoc config file strictdoc.toml + :class: image + :width: 100% diff --git a/docs/sphinx/source/strictdoc_02_faq.rst b/docs/sphinx/source/strictdoc_03_faq.rst similarity index 79% rename from docs/sphinx/source/strictdoc_02_faq.rst rename to docs/sphinx/source/strictdoc_03_faq.rst index 40e037d17..7be432dfa 100644 --- a/docs/sphinx/source/strictdoc_02_faq.rst +++ b/docs/sphinx/source/strictdoc_03_faq.rst @@ -3,6 +3,13 @@ F.A.Q. $$$$$$ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 5acdfccd5771492f95b70328bd599cf7 + This document is a list of questions that people ask about StrictDoc. Missing a question or an answer? Ask it here: :ref:`Contact the developers `. @@ -10,6 +17,13 @@ Missing a question or an answer? Ask it here: :ref:`Contact the developers `_. 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. @@ -38,6 +59,13 @@ Screencasts/tutorials: Which web server is recommended for StrictDoc documentation? ============================================================ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 966a5c3babf84fc7a1454b2799d13470 + 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. @@ -51,6 +79,13 @@ If the project is private, you could use any server that reads HTML files from a Is StrictDoc compatible with Sphinx? ==================================== +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - ac35a712b4a84f4ab2b61feb15c1550d + 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. @@ -64,89 +99,19 @@ There are users of StrictDoc who use both StrictDoc and Sphinx. The following wo 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 `_. +.. _SECTION-FAQ-How-did-the-SDoc-text-language-become-what-it-is: + How did the SDoc text language become what it is? ================================================= -Shortly: The SDoc markup is a hybrid of TOML and YAML with some influence from HTML/XML and `ASN.1 `_. Using each of these formats as-is, and also the JSON format, was considered but discarded during the design. The SDoc markup has been pretty stable since its inception but the flexibility of the TextX parser allows easy modifications of the language in case of future evolutions. Any feedback to the current design of the markup language is appreciated. - ----- - -The main use case for SDoc is to model a structure of a technical document that consists of tens and hundreds of technical requirements. The following high-level requirements for the markup are therefore relevant: - -- Encode documents of reasonable size (up to several hundreds or few thousands of A4-printed pages). -- Visualize large blocks of requirements text without too much markup noise. -- Support documents with nested (2-4 levels) or deeply nested structure (detailed technical specifications with up to 9-10 levels of chapter nesting). -- Support multiple fields for requirement meta information which makes a requirement look like "a text with some meta information around it". - -SDoc format is inspired by several formats: TOML, YAML, ASN.1 and HTML/XML. - -**TOML: Square bracket syntax** - -From TOML, StrictDoc borrowed the ``[]`` bracket syntax to create the ``[REQUIREMENT]``, ``[SECTION]`` and other blocks but uses the YAML-like syntax for these blocks' fields, for example: - -.. code-block:: - - [REQUIREMENT] - TITLE: Requirement ABC - STATEMENT: The system A shall do B when C. - -**TOML/YAML: Arrays/dictionaries** - -StrictDoc has a rudimentary support of arrays and dictionaries. For example, the syntax for defining the document's ``[GRAMMAR]`` resembles what would look like an array of records in YAML: - -.. code-block:: - - [GRAMMAR] - ELEMENTS: - - TAG: REQUIREMENT - FIELDS: - - TITLE: UID - TYPE: String - REQUIRED: True - - TITLE: LEVEL - TYPE: String - REQUIRED: False - -**Capitalization of reserved keywords from ASN.1** - -From ASN.1, StrictDoc borrows the idea of having all reserved fields capitalized. This helps to visually distinguish between the grammar content and user content. +.. list-table:: + :align: left + :header-rows: 0 -**Nested sections** + * - **MID:** + - b3561dd4f8e64f11a251c3471022aece -From HTML, the idea of opening and closing tags is taken to avoid any nesting that would otherwise be required to support the deeply nested documents with up to 6 or 8 levels, e.g., 1.1.1.1.1.1.1... - -.. code-block:: - - [SECTION] - TITLE: Section 1 - - [SECTION] - TITLE: Section 1.1 - - ... - - [/SECTION] - - [/SECTION] - -Taking HTML or XML as-is didn't seem like a good option because of the heavy visual noise that is produced around the actual content by the surrounding tags. - -**Multiline strings** - -The support of multiline strings is arranged by a custom solution which helps to avoid any nesting of multiline text as well as to visually indicate the start and end parts of the multiline string in a visually unambiguous way. This is how the multiline string is declared: - -.. code-block:: - - [REQUIREMENT] - TITLE: Requirement ABC - STATEMENT: >>> - The multiline requirement statement - without any nesting. - >>> - -**Discarded options** - -Taking TOML or YAML as-is didn't seem like a good option because these formats are designed to be used for configuration files or data serialization and not for large documents with hundreds of requirements. The most obvious problems for reusing either of TOML or YAML directly would have been with encoding the deeply nested documents and supporting readable and non-nested multiline strings. +See :ref:`SDoc text markup ` for a description of the SDoc feature. How StrictDoc compares to other tools? ====================================== @@ -154,6 +119,13 @@ How StrictDoc compares to other tools? Doorstop -------- +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - d0c305180d8747a1b70254eaf2c4f201 + The StrictDoc project is a close successor of another project called `Doorstop `_. @@ -205,6 +177,13 @@ to/from Doorstop format. Sphinx ------ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 74b6be0dc2bb485987d8731348cdf5ce + 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 @@ -225,6 +204,13 @@ website by readthedocs which uses Sphinx under the hood. The Sphinx-Needs ------------ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 602327a9b8654e1eab4bc265e172a63d + `Sphinx-Needs `_ is a text-based requirements management system based on Sphinx. It is implemented as a Sphinx extension which extends the @@ -281,6 +267,13 @@ The difference between Sphinx-Needs and StrictDoc: FRET ---- +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - e3eb1be604c6499292339ecbe7620c60 + `FRET `_ is a framework for the elicitation, specification, formalization and understanding of requirements. @@ -299,6 +292,13 @@ FRET's user interface is built with Electron. How long has the StrictDoc project been around? =============================================== +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 47d60404cf574aebb8c83795589c4137 + The first StrictDoc commit dates back to ``2019-08-10``. A short development chronology of StrictDoc is as follows: **2019 – July – August** @@ -333,6 +333,13 @@ See also: :ref:`Project milestones `. Which StrictDoc statistics are available? ========================================= +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 730bfedff6b24c34a6d6331051fd76d3 + Most relevant GitHub statistics: - `Contributors `_ diff --git a/docs/sphinx/source/strictdoc_03_release_notes.rst b/docs/sphinx/source/strictdoc_04_release_notes.rst similarity index 88% rename from docs/sphinx/source/strictdoc_03_release_notes.rst rename to docs/sphinx/source/strictdoc_04_release_notes.rst index 8ec62dc91..2bc2fad9b 100644 --- a/docs/sphinx/source/strictdoc_03_release_notes.rst +++ b/docs/sphinx/source/strictdoc_04_release_notes.rst @@ -1,11 +1,45 @@ Release Notes $$$$$$$$$$$$$ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 0dd2649ec4784c9480eac6f4aef3158b + 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 `_. +0.2.1 (2024-11-10) +================== + +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 26043bba142a4e739dd206e229829202 + +This release includes a new feature, a bug fix, and some documentation updates. + +- The ``[LINK: ...]`` feature now supports linking to documents by UID. [@haxtibal] +- HTML escaping was fixed on the Diff/Changelog screen. [@haxtibal] + +The documentation now includes two new pages: + +- The "Feature Map" document provides a high-level overview of the major StrictDoc features from the user's perspective. +- The Troubleshooting document offers advice on clearing the user cache, one of the common solutions to user issues. We plan to expand this section with more tips over time. + 0.2.0 (2024-11-04) ================== +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 611e8df13d464fd1b22e5026cf3ce531 + This release introduces several enhancements to the source code processing introduced in release 0.1.0. The backend now supports improved function tracing in C, Python, and general parsing code: @@ -21,6 +55,13 @@ Additionally, caching has been centralized, and the cache directory is now confi 0.1.0 (2024-11-01) ================== +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - e37e230c932448798bd9978d4f27f32c + This backward-compatible release introduces several new features for tracing requirements to source files: - StrictDoc now integrates with `Tree-sitter `_, enabling it to parse multiple programming languages. Using AST information, it achieves more precise tracing of requirements to source code. @@ -32,6 +73,13 @@ With this release, we are also transitioning to a more `semantic versioning `. @@ -96,6 +165,13 @@ Other changes in this release: 0.0.56 (2024-06-02) =================== +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 61f17be85ac442a0b70003825d671ced + This is an intermediate bugfix release before the release which will contain major changes. The following issues have been fixed: @@ -115,6 +191,13 @@ The following issues have been fixed: 0.0.55 (2024-04-28) =================== +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 00abb07e55534a75a8cfd50d8cfc5732 + The ReqIF export/import feature was extended to support three new command-line options for an improved export/import interfacing with Polarion. See :ref:`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. @@ -124,6 +207,13 @@ StrictDoc's caching feature was extended to work around pickling errors when an 0.0.54 (2024-04-17) =================== +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - e5bf489ac0684ea4b626574b5439c7dd + 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. @@ -136,6 +226,13 @@ StrictDoc's caching feature was extended to work around pickling errors when an 0.0.53 (2024-04-01) =================== +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 2ac296f6326b4481beb7d67b95dbb23c + 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. @@ -143,11 +240,25 @@ All code related to pybtex/BibTeX bibliographies has been removed from the Stric 0.0.52 (2024-03-25) =================== +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 72d6e38e89cc471b8d3f46ae5654e0e6 + 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. 0.0.51 (2024-03-20) =================== +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - e81c4206bcb148979762ee3f2aa5c9ba + 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. @@ -155,6 +266,13 @@ A regression was introduced during recent internal refactoring, resulting in mal 0.0.50 (2024-03-19) =================== +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - a9d7c449d1a7400496504926c744e500 + **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]``. @@ -172,6 +290,13 @@ A regression was introduced during recent internal refactoring, resulting in mal 0.0.49 (2024-03-11) =================== +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 0b8c8f40923744b089845afeb44223e9 + 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. @@ -187,6 +312,13 @@ The Excel export algorithm was extended to support generating multiple Excel fil 0.0.48 (2024-01-24) =================== +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 6cff333594d6430886053b59b265e806 + 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. @@ -204,6 +336,13 @@ The Requirements Coverage has been transformed into **the Traceability Matrix** 0.0.47 (2023-11-20) =================== +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - c422af340d5b45c48bfe89130e1bba52 + 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. diff --git a/docs/sphinx/source/strictdoc_04_troubleshooting.rst b/docs/sphinx/source/strictdoc_05_troubleshooting.rst similarity index 83% rename from docs/sphinx/source/strictdoc_04_troubleshooting.rst rename to docs/sphinx/source/strictdoc_05_troubleshooting.rst index 857a8cb21..c259bb33c 100644 --- a/docs/sphinx/source/strictdoc_04_troubleshooting.rst +++ b/docs/sphinx/source/strictdoc_05_troubleshooting.rst @@ -3,11 +3,25 @@ Troubleshooting $$$$$$$$$$$$$$$ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 7e3481d51ad14767b5c97132cad2e0a6 + This document summarizes solutions to the most common issues reported by StrictDoc users. Caching issues ============== +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 9a32ac13510d401cbc1a608259652c78 + .. note:: **TL;DR:** If you encounter errors related to reading data, make sure to delete the StrictDoc cache folder located at ``$TMPDIR/strictdoc_cache`` or in the custom directory if specified by the ``cache_dir`` option in the ``strictdoc.toml`` configuration file. diff --git a/docs/sphinx/source/strictdoc_10_contributing.rst b/docs/sphinx/source/strictdoc_10_contributing.rst index 07c89466a..6c8b1f69b 100644 --- a/docs/sphinx/source/strictdoc_10_contributing.rst +++ b/docs/sphinx/source/strictdoc_10_contributing.rst @@ -1,6 +1,13 @@ Contributing to StrictDoc $$$$$$$$$$$$$$$$$$$$$$$$$ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 13fe652f160d4af69e869c28a155437d + Contributions to StrictDoc are welcome and appreciated. Presented below is a condensed checklist that summarises the information of the development guide, see :ref:`Getting started `. @@ -8,6 +15,13 @@ of the development guide, see :ref:`Getting started `. Contributor checklist ===================== +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - ae0fc6d87b114137ab6da7c9b5647b62 + Before opening your Pull Request, the contributor is encouraged to do the following steps: @@ -30,6 +44,13 @@ How can I help? Spread the word --------------- +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 07462b02027a423a85ab68525b78ac67 + 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. @@ -39,6 +60,13 @@ If you like the StrictDoc project and use it in your daily work, there are sever ReqIF users ----------- +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 9cfbb025525f41c5a195be0e637dffee + 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/. @@ -46,6 +74,13 @@ It is straightforward to create an anonymized version of a ReqIF file. Just redu TeX / LaTeX / Sphinx experts ---------------------------- +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 75ed9362d86748269f62f5920514b7c2 + 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. diff --git a/docs/sphinx/source/strictdoc_11_developer_guide.rst b/docs/sphinx/source/strictdoc_11_developer_guide.rst index 3e566cfc7..5cc012177 100644 --- a/docs/sphinx/source/strictdoc_11_developer_guide.rst +++ b/docs/sphinx/source/strictdoc_11_developer_guide.rst @@ -1,6 +1,13 @@ Developer Guide $$$$$$$$$$$$$$$ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - f174b0cdec6b482daa2878c8cc0d02c3 + This section contains everything that a StrictDoc developer/contributor should know to get the job done. @@ -21,6 +28,13 @@ Getting started System dependencies ------------------- +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - df2e1de12c6b456898c48a36650813d4 + 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. @@ -40,6 +54,13 @@ From the core Python packages, StrictDoc needs Invoke, Tox and TOML: Windows-specific: Long Path support ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 8591cf6dece04244824c3ac2a8666ba3 + 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. @@ -47,6 +68,13 @@ You can find information on how to enable the long paths support at https://pip. Installing StrictDoc from GitHub (developer mode) ------------------------------------------------- +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 2407bb186b274a58b97b54b99ba6e86f + **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``. @@ -61,6 +89,13 @@ The ``pip_install_strictdoc_deps.py`` installs all dependencies of StrictDoc, bu Invoke for development tasks ============================ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 452b3c24463446a497ed6b8fcdb31fef + 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 @@ -76,6 +111,13 @@ Make sure to familiarize yourself with the available developer tasks by running: Main "Check" task ================= +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 09258e99cabb4455904b0e2c6687d492 + Before doing anything else, run the main ``check`` command to make sure that StrictDoc passes all tests on your system: .. code:: bash @@ -89,6 +131,13 @@ The ``check`` command runs all StrictDoc lint and test tasks with the only excep Python code =========== +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 3012a69ef5d244d49fcb90c088d4523b + - 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 @@ -125,6 +174,13 @@ Python code Git workflow ============ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 0e916453596b460b84a89f722354a825 + - 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 @@ -166,6 +222,13 @@ where the context can be a major feature being added or a folder. A form of ``c Frontend development ==================== +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - d818aad87db54985b8933f98528808ab + The shortest path to run the server when the StrictDoc's source code is cloned: .. code-block:: bash @@ -175,6 +238,13 @@ The shortest path to run the server when the StrictDoc's source code is cloned: Running End-to-End Web tests ============================ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - da3cbcd69b0545988daeb0f42098830d + .. code:: bash invoke test-end2end @@ -182,6 +252,13 @@ Running End-to-End Web tests Running integration tests ========================= +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 4e307b3b950840bbbe455c1ae3238a6e + The integration tests are run using Invoke: .. code-block:: bash @@ -199,6 +276,13 @@ See `How to test command-line programs with Python tools: LIT and FileCheck `_-oriented release scheme. The MAJOR.MINOR.PATCH components are managed according to the guidelines of the semantic versioning specification. Verification ============ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 14d0e79fcadc43f1a1cee2d66ae6b763 + StrictDoc has three groups of tests: unit, integration, end-to-end tests. The unit tests are based on Pylint. @@ -117,6 +159,13 @@ The end-to-end web interface tests are based on SeleniumBase test framework. Python baseline =============== +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 081ee6266bab4a3a80f290c95e055a25 + 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. diff --git a/docs/sphinx/source/strictdoc_25_design.rst b/docs/sphinx/source/strictdoc_25_design.rst index caacff662..3cff43cc0 100644 --- a/docs/sphinx/source/strictdoc_25_design.rst +++ b/docs/sphinx/source/strictdoc_25_design.rst @@ -3,11 +3,25 @@ Design Document $$$$$$$$$$$$$$$ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 2c006e9044074d239db4a45328633657 + 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. Overview ======== +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 23937f96ac8e437d81686071cc42d6bf + StrictDoc consists of two applications: 1. StrictDoc command-line application (CLI). @@ -18,6 +32,13 @@ Both applications share a significant subset of the backend and frontend logic. Building blocks =============== +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - bae7db5591fe418a857af4fb02ad4fec + StrictDoc is based on the following open-source libraries and tools: .. list-table:: @@ -53,6 +74,13 @@ StrictDoc is based on the following open-source libraries and tools: High-level architecture ======================= +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - dcb6369b8d0949f0b06c9ee5b2188b12 + The following diagram captures the high-level architecture of StrictDoc. .. image:: _assets/StrictDoc_Workspace-Architecture.drawio.png @@ -63,6 +91,13 @@ The following diagram captures the high-level architecture of StrictDoc. StrictDoc command-line application ================================== +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 0e0fca629004496084dbe5e217874c36 + 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: @@ -75,6 +110,13 @@ The command-line application can be seen as a Model-View-Controller application: StrictDoc web application ========================= +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - f84c0efa27954e44a8b5c1dd3517f90f + 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. @@ -85,6 +127,13 @@ StrictDoc Web application is based on FastAPI / Uvicorn. The end-to-end usage cy The HTML Over the Wire (Hotwire) architecture --------------------------------------------- +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 5577da2187294eb986ec84d9fe26bbdf + 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. @@ -96,6 +145,13 @@ Currently, the web server renders the HTML documents using the same generators t Parsing SDoc files ================== +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 8a926f0a67424a1eb5db73bb5abca0cd + 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: @@ -111,6 +167,13 @@ One important implementation detail of Arpeggio that influences StrictDoc user e Caching artifacts ================= +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - d351d1bf6c2a48d88e9b9bdc50e029ff + StrictDoc caches artifacts to disk to speed up performance by avoiding repeated reading and computation of already-parsed objects. The cached artifacts include: @@ -128,6 +191,13 @@ An MD5 checksum is generated for a piece of content, and a file with this checks HTML escaping ============= +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - e8a03713c7f644698d9a72cc79b2a299 + StrictDoc uses Jinja2 autoescaping_ for HTML output. `Template.render`_ calls will escape any Python object unless it's explicitly marked as safe. diff --git a/docs/sphinx/source/strictdoc_30_credits.rst b/docs/sphinx/source/strictdoc_30_credits.rst index 1a17a5989..0ccaf7fa4 100644 --- a/docs/sphinx/source/strictdoc_30_credits.rst +++ b/docs/sphinx/source/strictdoc_30_credits.rst @@ -1,6 +1,13 @@ Credits $$$$$$$ +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 18cf0af34c194590b3eb391c2ef94074 + As an open-source project, StrictDoc is based on the work of many people and organizations: - StrictDoc receives contributions from other developers. @@ -13,6 +20,13 @@ This page gives due credit to everyone who made StrictDoc possible. Contributions to StrictDoc ========================== +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - e6de83e242bc4aea96622a2e7585f135 + The core team: @stanislaw and @mettta. The following people and organizations have contributed to StrictDoc. The contributions are listed in the alphabetic order. @@ -34,6 +48,13 @@ Single/smaller contributions can be also seen on the `StrictDoc's Insights/Contr Open source software ==================== +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - 4428ac9ec3504dda9f1e1e845ffb3c75 + 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,6 +82,13 @@ Refer to the `configuration file `_ 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 `_. @@ -68,6 +96,13 @@ StrictDoc's documentation is hosted on `Read the Docs ` Free and commercial IDEs by JetBrains ===================================== +.. list-table:: + :align: left + :header-rows: 0 + + * - **MID:** + - b4729e592d104fe3818c8949615ffef9 + For Python development, the StrictDoc core team uses the community version of `PyCharm `_ from `JetBrains `_. diff --git a/docs/strictdoc_03_faq.sdoc b/docs/strictdoc_03_faq.sdoc index acc61637b..7c2047411 100644 --- a/docs/strictdoc_03_faq.sdoc +++ b/docs/strictdoc_03_faq.sdoc @@ -207,7 +207,7 @@ and other formats using Sphinx. If you are reading this documentation at https://strictdoc.readthedocs.io/en/latest then you are already looking at the example: this documentation stored in -`strictdoc_02_faq `_ +`strictdoc_03_faq `_ is converted to RST format by StrictDoc which is further converted to the HTML website by readthedocs which uses Sphinx under the hood. The ``StrictDoc -> RST -> Sphinx -> PDF`` example is also generated using readthedocs: diff --git a/docs/strictdoc_04_release_notes.sdoc b/docs/strictdoc_04_release_notes.sdoc index b0adfe81b..4c5c2ec8e 100644 --- a/docs/strictdoc_04_release_notes.sdoc +++ b/docs/strictdoc_04_release_notes.sdoc @@ -24,6 +24,26 @@ 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 `_. <<< +[SECTION] +MID: f4cd860f07b1479ba1845bce3c749d68 +TITLE: 0.2.1 (2024-11-10) + +[TEXT] +MID: 26043bba142a4e739dd206e229829202 +STATEMENT: >>> +This release includes a new feature, a bug fix, and some documentation updates. + +- The ``[LINK: ...]`` feature now supports linking to documents by UID. [@haxtibal] +- HTML escaping was fixed on the Diff/Changelog screen. [@haxtibal] + +The documentation now includes two new pages: + +- The "Feature Map" document provides a high-level overview of the major StrictDoc features from the user's perspective. +- The Troubleshooting document offers advice on clearing the user cache, one of the common solutions to user issues. We plan to expand this section with more tips over time. +<<< + +[/SECTION] + [SECTION] MID: f76d863243b5410788e457b9c3bf1d2b TITLE: 0.2.0 (2024-11-04) diff --git a/strictdoc/__init__.py b/strictdoc/__init__.py index 0475a4f3c..4e92263f7 100644 --- a/strictdoc/__init__.py +++ b/strictdoc/__init__.py @@ -1,6 +1,6 @@ from strictdoc.core.environment import SDocRuntimeEnvironment -__version__ = "0.2.0" +__version__ = "0.2.1" environment = SDocRuntimeEnvironment(__file__)