Merge pull request strictdoc-project#1619 from strictdoc-project/stan…

…islaw/release_

Bump version to 0.0.48

docs/sphinx/source/DO178_requirements.rst

@@ -1,7 +1,7 @@
-DO-178C requirements tool requirements
-$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$
+Technical Note: DO-178C requirements tool requirements
+$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$
 
-This document outlines a set of high-level requirements for StrictDoc, a text-based requirements management system. While StrictDoc already meets many of these requirements, further discussion is needed to clarify any remaining questions. For the outstanding requirements, we can establish a practical implementation plan within the upcoming 2023-2024 StrictDoc roadmap.
+This document outlines a set of high-level requirements for StrictDoc, a text-based requirements management system. While StrictDoc already meets many of these requirements, a further discussion is needed to clarify any remaining questions. For the outstanding requirements, we can establish a practical implementation plan within the upcoming 2023-2024 StrictDoc roadmap.
 
 These requirements are recommended by engineers who adhere to the DO-178B and DO-178C standards of the aviation industry. For a visual summary of the DO-178 standard, please refer to this link: https://upload.wikimedia.org/wikipedia/commons/4/4f/DO-178B_Process_Visual_Summary_Rev_A.pdf.
 
@@ -275,7 +275,7 @@ Source file coverage
     * - **UID:**
       - DO178-13
     * - **STATUS:**
-      - Backlog
+      - Active
 
 StrictDoc shall support generation of source code coverage information.
 
@@ -328,7 +328,7 @@ Diff between document trees
     * - **UID:**
       - DO178-15
     * - **STATUS:**
-      - Backlog
+      - Active
 
 StrictDoc shall allow calculating Diff between two document trees.
 
@@ -356,7 +356,7 @@ Traceability matrices
     * - **COMPLIANCE:**
       - C
     * - **STATUS:**
-      - Backlog
+      - Active
 
 StrictDoc shall support generation of forward and backward traceability matrices.
 
@@ -429,7 +429,7 @@ Uncovered requirement report
     * - **COMPLIANCE:**
       - C
     * - **STATUS:**
-      - Backlog
+      - Active
 
 StrictDoc shall support generation of uncovered requirement report.
 

docs/sphinx/source/Zephyr_requirements.rst

@@ -1,5 +1,5 @@
-Zephyr requirements tool requirements
-$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$
+Technical Note: Zephyr requirements tool requirements
+$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$
 
 .. _ZEP-1:
 

docs/sphinx/source/strictdoc_01_user_guide.rst

@@ -2095,6 +2095,23 @@ this option will only have effect on the HTML export. All other export options
 are run from the main thread. Reading of the SDoc documents is parallelized for
 all export options and is disabled with this option as well.
 
+Python API
+==========
+
+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 <SECTION-DD-High-level-architecture>`.
+
+One good example is the ``SDWriter`` class, which exercises the complete export of the Python data objects to the SDoc format. Since, the SDoc format is the primary data format of StrictDoc, the SDWriter is quite feature-rich in what it does and covers. The ``RSTWriter`` is less powerful because it does not reflect the full data model, but is probably worth a look as well.
+
+The ``strictdoc/backend/reqif`` folder contains exporter/importer routines for the ReqIF format. There, the core classes from the Python data model, e.g. Requirement, Section, Document, Grammar, etc. are created or read from and to the ReqIF format.
+
+The ``ManageAutoUIDCommand`` class features a good use of all APIs that one may need to read/update/write back a SDoc document tree:
+
+- The ``TraceabilityIndex`` is created from a project config. The traceability index is the main class for storing the whole traceability graph in Python objects. It has plenty of methods for reading and writing things from the graph.
+- The ``DocumentUIDAnalyzer`` is an example of how the objects are manipulated in memory.
+- And finally the final sequence writes the mutated traceability graph back to files using ``SDWriter``.
+
+For any custom Python API request, for example, a need to do a more advanced data analysis on SDoc data, open a GitHub issue and your specific issue will be handled.
+
 .. _SDOC_UG_EXPERIMENTAL_FEATURES:
 
 Experimental features
@@ -2129,7 +2146,7 @@ This feature is not enabled by default because it has not undergone sufficient t
 HTML2PDF printable document generator
 -------------------------------------
 
-The HTML2PDF screen displays a browser-printable version of a document. Printing from a browser results in a well-formatted PDF document or a well-formatted document printed on paper.
+The HTML2PDF screen displays a browser-printable version of a document. Printing from a browser results in a well-formatted PDF document or a well-formatted document printed on paper. The best printing experience is achieved with the Chrome browser which in contrast to Firefox and Safari, preserves the internal hyperlinks in the output PDF.
 
 To activate the HTML2PDF screen, add/edit the ``strictdoc.toml`` config file in the root of your repository with documentation content.
 
@@ -2142,7 +2159,7 @@ To activate the HTML2PDF screen, add/edit the ``strictdoc.toml`` config file in
       "HTML2PDF"
     ]
 
-This feature is not enabled by default because the implementation has not been completed yet. The underlying JavaScript library is being improved with respect to our HTML content is split between pages, in particular the splitting of HTML ``<table>`` tags is being worked on. One feature that is still missing is the ability to generate user-specific front pages with custom meta information. Another feature to be added is the "Export document to PDF" button.
+This feature is not enabled by default because the implementation has not been completed yet. The underlying JavaScript library is being improved with respect to our HTML content is split between pages, in particular the splitting of HTML ``<table>`` tags is being worked on. One feature that is still missing is the ability to generate user-specific front pages with custom meta information.
 
 Mermaid diagramming and charting tool
 -------------------------------------
@@ -2234,3 +2251,40 @@ Concurrent use of web user interface
 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.
+
+Known issues
+============
+
+This section documents some known issues and non-obvious implementation details.
+
+.. _SDOC_IMPL_1:
+
+Exporting document free text to ReqIF and vice versa
+----------------------------------------------------
+
+ReqIF format does not seem to provide a dedicated convention for a text node to be distinguished from a requirement or a section. StrictDoc implements a workaround: the document's free text is converted to a section with a ``ChapterName`` field that equals "Abstract". And the other way round: when a ReqIF-to-SDoc converter encounters the first section of a document to be "Abstract", it is converted to a free text.
+
+.. _SDOC_IMPL_2:
+
+Running out of semaphores on macOS
+----------------------------------
+
+This an edge case on macOS: Python crashes in the Parallelizer class when
+creating an output queue:
+
+.. code-block:: py
+
+    self.output_queue = multiprocessing.Queue()
+
+The fragment of the crash:
+
+.. code-block:: text
+
+    sl = self._semlock = _multiprocessing.SemLock(
+    OSError: [Errno 28] No space left on device
+
+The existing workaround for this problem is to increase a number of semaphores in the macOS config:
+
+.. code-block:: text
+
+    sudo sysctl -w kern.posix.sem.max=20000

docs/sphinx/source/strictdoc_03_development_plan.rst

@@ -7,104 +7,27 @@ project is developed.
 Project goals
 =============
 
-StrictDoc is an attempt to create an open source tool for writing
-technical requirements specifications.
+StrictDoc is an open-source tool for writing technical documentation and requirements management. The long-term goal of the project is to provide a capable, open-source platform for creating and managing technical documentation.
 
-.. _GOAL-1-TOOL-SUPPORT:
+**Requirements automation**
 
-Software support for writing requirements and specifications documents
-----------------------------------------------------------------------
+The tool aims to automate the requirements documentation process at various levels.
 
-.. list-table::
-    :align: left
-    :header-rows: 0
-
-    * - **UID:**
-      - GOAL-1-TOOL-SUPPORT
-
-There shall exist free and lightweight yet capable software for writing
-requirements and specifications documents
-
-**Comment:**
-
-Technical documentation is hard, it can be an extremely laborious process.
-Software shall support engineers in their work with documentation.
-
-.. _GOAL-2-REDUCE-DOCUMENTATION-HAZARDS:
-
-Reduce documentation hazards
-----------------------------
-
-.. list-table::
-    :align: left
-    :header-rows: 0
-
-    * - **UID:**
-      - GOAL-2-REDUCE-DOCUMENTATION-HAZARDS
-
-There shall exist no (or less) opportunity for writing incorrect or inconsistent
-documentation.
-
-**Comment:**
-
-Every serious engineering activity, such as safety engineering or systems
-engineering, starts with requirements. The more critical is a product the higher
-the importance of good documentation.
-
-Technical documentation can be and often becomes a source of hazards.
-It is recognized that many failures stem from inadequate requirements
-engineering. While it is not possible to fix the problem of inadequate
-requirements engineering in general, it is definitely possible to improve
-software that supports engineers in activities such as requirements engineering
-and writing technical documentation.
-
-.. _GOAL-3-NO-RUNAWAY-DOCUMENTATION:
-
-No (or less) run-away documentation
------------------------------------
-
-.. list-table::
-    :align: left
-    :header-rows: 0
-
-    * - **UID:**
-      - GOAL-3-NO-RUNAWAY-DOCUMENTATION
-
-Software shall support engineers in keeping documentation up-to-date.
-
-**Comment:**
-
-Technical documentation easily becomes outdated. Many existing tools for
-documentation do not provide any measures for ensuring overall consistency of
-documents and documentation trees.
-
-.. _GOAL-4-CHANGE-MANAGEMENT:
-
-Change management
------------------
-
-.. list-table::
-    :align: left
-    :header-rows: 0
+**Target groups**
 
-    * - **UID:**
-      - GOAL-4-CHANGE-MANAGEMENT
+The project targets different user groups including those in software, hardware, systems (systems engineering, electrical, thermal), as well as quality assurance, safety, management, and non-technical areas.
 
-Software shall provide capabilities for change management and impact assessment.
+**Use on individual computers and cloud**
 
-**Comment:**
+The project is already usable on individual personal computer, the long-term goal is to enable its use on cloud.
 
-Change management is difficult. The bigger the project is, the harder it is to
-maintain its documentation. If a change is introduced to a project, it usually
-requires a full revision of its requirements.
+**Open data**
 
-**Comment:**
+An important feature of StrictDoc is its focus on open data, ensuring ease of data transfer both into and out of the system.
 
-When the basic capabilities of StrictDoc are in place, it should be possible
-to do a more advanced analysis of requirements and requirement trees:
+**Synergies with other tools**
 
-- Finding similar or relevant requirements.
-- Enforce invariants that should be hold. Example: mass or power budget.
+StrictDoc shall be compatible with other software and engineering tools. This includes at least the compatibility with the Python ecosystem, the model-based systems engineering tools, such as Capella, and the formats providing Software Bill of Materials, such as SPDX.
 
 Project milestones
 ==================

docs/sphinx/source/strictdoc_04_release_notes.rst

@@ -3,16 +3,22 @@ $$$$$$$$$$$$$
 
 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 <https://github.com/strictdoc-project/strictdoc/blob/main/CHANGELOG.md>`_.
 
-Unreleased work
-===============
+0.0.48 (2024-01-24)
+===================
 
 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`` search path filters specified, and an input document path contradicts to the provided filters, a validation message is shown.
+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.
+
+The Project Statistics screen was extended with the **"Sections without any text" metric**. Now it is possible to visualize which sections are still missing any introduction or description (free text).
+
+**The new Machine Identifier (MID)** field has been added to StrictDoc's grammar. The automatic generation of MIDs can be activated per-document using the ``ENABLE_MID: True`` document-level config option. The main driver for this feature is the need of accurate Diff/Changelog results. The new section of the User Guide explains the rationale and the configuration details: :ref:`Machine identifiers (MID) <SECTION-UG-Machine-identifiers-MID>`.
+
+**The Diff and Changelog screens** have been introduced to facilitate a historical comparison of documentation trees. The Diff screen aids in focusing on which document nodes have been altered, while the Changelog functions as a sequential table where changes are displayed as table cells and each cell emphasizes specific details of a particular change.
 
-The Project Statistics screen was extended with the "Sections without any text" metric. Now it is possible to visualize which sections are still missing any introduction or description (free text).
+The Requirements Coverage has been transformed into **the Traceability Matrix** screen. This matrix screen lists all nodes of a documentation graph, along with all their interrelations. The currently generated screen is entirely static. However, future enhancements are planned to include filtering capabilities for the content. The Traceability Matrix feature is disabled by default and has to be activated as ``TRACEABILITY_MATRIX_SCREEN`` in the strictdoc.toml project config file.
 
-The new Machine Identifier (MID) field has been added to StrictDoc's grammar. The automatic generation of MIDs can be activated per-document using the ``ENABLE_MID: True`` document-level config option. The main driver for this feature is the need of accurate Diff/Changelog results. The new section of the User Guide explains the rationale and the configuration details: :ref:`Machine identifiers (MID) <SECTION-UG-Machine-identifiers-MID>`.
+**The HTML2PDF feature** has now entered the alpha testing phase. This feature enables printing of documents directly from a browser, which can be done either through the "PDF" screen view or by utilizing the "Export to PDF" button. By default, the HTML2PDF feature is disabled. To activate it, you need to indicate the ``HTML2PDF`` feature in the strictdoc.toml project configuration file.
 
 0.0.47 (2023-11-20)
 ===================