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.
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.
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.
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].
Rather than importing section-like fragments, standard SDoc documents can now be included within other SDoc documents.
The web interface has been updated to support viewing and editing documents both as standalone items and when they are included in other documents.
Not everything related to the composable documents has been implemented. For example, the ability to drag and drop TOC (Table of Contents) nodes in documents that include other documents. Currently, moving the TOC in documents that include other documents is disabled.
Further work for the editable web interface can be found here: https://github.com/strictdoc-project/strictdoc/issues/1698.
Other changes:
The functionality of the HTML2PDF script on Windows has been corrected for scenarios where StrictDoc is operated within a virtual environment. Special thanks to @Timotheous for highlighting this issue.
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.
Thanks to the work by @dahbar, the SDoc grammar and the web interface have been extended to allow assigning a human title to each field of a grammar element. For example, the UID field can be now displayed as Unique identifier in the web interface and the static HTML export.
The layout of the PDF document generated by the HTML2PDF conversion process has been improved. Several edge cases, such as the breaks between sentences, have been fixed.
The source file identification mechanism of the requirement-to-source traceability feature has been expanded to locate all source files present in a given source input directory. Previously, it was limited to finding files with specific extensions such as .c, .py, .sdoc, .rst, among others. This restriction, originally implemented for historical reasons, has now been removed. Moreover, StrictDoc has now integrated the get_lexer_by_name() function to automatically identify a lexer based on a source file’s extension. This enhancement help StrictDoc to offer syntax highlighting tailored specifically to the format of each source file. Previously, StrictDoc’s code directly hardcoded only a limited selection of Pygments’ lexers. Thanks to @KlfJoat for helping us to prioritize and fix this issue sooner.
The Excel export algorithm was extended to support generating multiple Excel files for documentation tree with requirements that link to each other across documents. The issue manifested itself as KeyError. Thanks to @Dynteq for reporting this.
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.
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: 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 Requirements Coverage has been transformed into the Traceability Matrix screen. This matrix screen lists all nodes of a documentation graph, along with all their interrelations. The currently generated screen is entirely static. However, future enhancements are planned to include filtering capabilities for the content. The Traceability Matrix feature is disabled by default and has to be activated as TRACEABILITY_MATRIX_SCREEN in the strictdoc.toml project config file.
The HTML2PDF feature has now entered the alpha testing phase. This feature enables printing of documents directly from a browser, which can be done either through the “PDF” screen view or by utilizing the “Export to PDF” button. By default, the HTML2PDF feature is disabled. To activate it, you need to indicate the HTML2PDF feature in the strictdoc.toml project configuration file.
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 <query> and filter-sections <query> 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.
The document option ROOT: True/False was introduced to indicate the root documents in the traceability graph. Currently, this option is only used when printing requirement statistics, where the root nodes are skipped when the metric “requirements without parents” is calculated. The root-level requirements by definition have no parent requirements, they can only be parents to other requirements.
When editing Section, it is now possible to auto-generate a section UID with a corresponding button which makes the management of section UIDs much easier.
The stability and the execution time of the CI end-2-end tests for the web interface has been increased. The sharding of the end-2-end tests was introduced for all systems: macOS, Linux, and Windows. At the same time, the number of Python versions that are tested by each platform’s jobs was reduced to maintain a reasonable total number of build jobs.
The requirement-to-source traceability feature was extended with the so-called single-line markers. Now it is possible to reference just a single line in a file by using the @sdoc(REQ-001) marker.
Python 3.12 support has been added to the GitHub CI jobs.
The second generation of StrictDoc’s requirements received many updates. The new requirements set will be incorporated to the main documentation very soon (estimated time is until the end of 2023). These requirements are maintained in the drafts/requirements folder.
The User Guide has been updated to include the “Security Considerations” chapter, which provides a warning about unsafe use of StrictDoc if it is deployed to a server on a public network.