From bd601df791d3a53eb37677c62f282e8e4e4efbe0 Mon Sep 17 00:00:00 2001 From: Stanislav Pankevich Date: Sun, 16 Jul 2023 18:39:29 +0200 Subject: [PATCH 1/2] drafts/requirements: more links --- .../requirements/10_concept/10_Concept.sdoc | 10 ++++++-- drafts/requirements/20_high_level/20_HLR.sdoc | 23 +++++++++++++++++-- drafts/requirements/strictdoc.toml | 20 ++++++++++++++++ 3 files changed, 49 insertions(+), 4 deletions(-) create mode 100644 drafts/requirements/strictdoc.toml diff --git a/drafts/requirements/10_concept/10_Concept.sdoc b/drafts/requirements/10_concept/10_Concept.sdoc index 35464566e..93d147f1c 100644 --- a/drafts/requirements/10_concept/10_Concept.sdoc +++ b/drafts/requirements/10_concept/10_Concept.sdoc @@ -292,8 +292,14 @@ TITLE: Programming access via API (SDK) [REQUIREMENT] UID: SDOC-RMC-49 -STATUS: Draft -TITLE: Programming access to requirements data +STATUS: Active +TITLE: Programmatic access to requirements data +STATEMENT: >>> +The Requirements Tool shall provide programmatic access to requirements data. +<<< +RATIONALE: >>> +When the requirements data is accessible by a user directly, it is possible to exchange the data or implement additional scripting procedures. +<<< [/SECTION] diff --git a/drafts/requirements/20_high_level/20_HLR.sdoc b/drafts/requirements/20_high_level/20_HLR.sdoc index 75a13ca69..4c3d5b381 100644 --- a/drafts/requirements/20_high_level/20_HLR.sdoc +++ b/drafts/requirements/20_high_level/20_HLR.sdoc @@ -215,9 +215,22 @@ REFS: VALUE: SDOC-RMC-39 - TYPE: Parent VALUE: SDOC-RMC-41 -- TYPE: Parent - VALUE: SDOC-RMC-49 TITLE: Progress report +STATEMENT: >>> +The Requirements Tool shall allow generating a Progress Report document. + +NOTE: A progress report document shall include at least the following Key Performance Indicators. + +Project-level KPIs: + +- Total number of requirements +- Total number of requirements without parent (excluding top-level and derived) +- Total number of TBD/TBC +- Total number of requirements without rationale +- Tags breakdown + +Document-level KPIs: the same but per document. +<<< [/SECTION] @@ -256,10 +269,16 @@ TITLE: Web interface [REQUIREMENT] UID: SDOC-SSS-32 +STATUS: Active REFS: - TYPE: Parent VALUE: SDOC-RMC-11 +- TYPE: Parent + VALUE: SDOC-RMC-49 TITLE: Command-line interface +STATEMENT: >>> +The Requirements Tool shall provide a command line interface (CLI). +<<< [REQUIREMENT] UID: SDOC-SSS-33 diff --git a/drafts/requirements/strictdoc.toml b/drafts/requirements/strictdoc.toml new file mode 100644 index 000000000..799cc6846 --- /dev/null +++ b/drafts/requirements/strictdoc.toml @@ -0,0 +1,20 @@ +[project] +title = "StrictDoc Documentation" +html_assets_strictdoc_dir = "assets" + +features = [ + # Stable features. + "TABLE_SCREEN", + "TRACEABILITY_SCREEN", + "DEEP_TRACEABILITY_SCREEN", + + # Stable features but not used by StrictDoc. + # "MATHJAX" + + # Experimental features are disabled when published to GitHub pages. + # "REQIF", + # "STANDALONE_DOCUMENT_SCREEN", + # "REQUIREMENTS_COVERAGE_SCREEN", + # "REQUIREMENT_TO_SOURCE_TRACEABILITY", + "HTML2PDF", +] From 5c293ae0d30f933c13138b2cc79d08b8db747abd Mon Sep 17 00:00:00 2001 From: Stanislav Pankevich Date: Sun, 16 Jul 2023 19:17:35 +0200 Subject: [PATCH 2/2] drafts/requirements: move DO-178C to the HLR level --- .../requirements/10_concept/10_Concept.sdoc | 31 +++ drafts/requirements/20_high_level/20_HLR.sdoc | 17 +- .../21_DO178.sdoc} | 229 +++++++++--------- .../screens/document/_shared/frame_toc.jinja | 2 +- 4 files changed, 162 insertions(+), 117 deletions(-) rename drafts/requirements/{10_concept/11_DO178.sdoc => 20_high_level/21_DO178.sdoc} (95%) diff --git a/drafts/requirements/10_concept/10_Concept.sdoc b/drafts/requirements/10_concept/10_Concept.sdoc index 93d147f1c..163e64903 100644 --- a/drafts/requirements/10_concept/10_Concept.sdoc +++ b/drafts/requirements/10_concept/10_Concept.sdoc @@ -385,23 +385,54 @@ TITLE: Formal modeling [REQUIREMENT] UID: SDOC-RMC-27 +STATUS: Backlog TITLE: Integration with other systems engineering processes +STATEMENT: >>> +The Requirements Tool shall provide capabilities for integration with other systems engineering tools. +<<< [REQUIREMENT] UID: SDOC-RMC-29 +STATUS: Backlog TITLE: Integration with Capella +STATEMENT: >>> +The Requirements Tool shall provide integration with Capella MBSE tool. +<<< +RATIONALE: >>> +Eclipse Capella is a capable open-source tool for Model-Based Systems Engineering, https://www.eclipse.org/capella/. It should be beneficial for the requirements tool to interface with the Capella engineering community. +<<< +COMMENT: >>> +At the very least, the integration can happen through the ReqIF interface that Capella is known to support. +<<< [REQUIREMENT] UID: SDOC-RMC-55 +STATUS: Backlog TITLE: Support STPA method +STATEMENT: >>> +The Requirements Tool shall provide support for the STPA method. +<<< [REQUIREMENT] UID: SDOC-RMC-28 +STATUS: Backlog TITLE: Formalized statements +STATEMENT: >>> +The Requirements Tool shall provide capabilities for hardening requirements content with formal semantics. +<<< +COMMENT: >>> +The directions to explore: +- NASA FRET +- bmw-software-engineering/trlc +<<< [REQUIREMENT] UID: SDOC-RMC-30 +STATUS: Backlog TITLE: AI Assistant +STATEMENT: >>> +The Requirements Tool shall provide integration with AI tools (e.g., ChatGPT). +<<< [/SECTION] diff --git a/drafts/requirements/20_high_level/20_HLR.sdoc b/drafts/requirements/20_high_level/20_HLR.sdoc index 4c3d5b381..c3ca09cc0 100644 --- a/drafts/requirements/20_high_level/20_HLR.sdoc +++ b/drafts/requirements/20_high_level/20_HLR.sdoc @@ -192,9 +192,10 @@ REFS: VALUE: SDOC-RMC-3 - TYPE: Parent VALUE: SDOC-RMC-39 -- TYPE: Parent - VALUE: DO178-10 TITLE: Traceability matrices +STATEMENT: >>> +The Requirements Tool shall support generation of traceability matrices. +<<< [REQUIREMENT] UID: SDOC-SSS-48 @@ -263,9 +264,10 @@ UID: SDOC-SSS-31 REFS: - TYPE: Parent VALUE: SDOC-RMC-36 -- TYPE: Parent - VALUE: DO178-6 TITLE: Web interface +STATEMENT: >>> +The Requirements Tool shall provide a web interface. +<<< [REQUIREMENT] UID: SDOC-SSS-32 @@ -319,10 +321,11 @@ following requirements apply. [REQUIREMENT] UID: SDOC-SSS-55 -REFS: -- TYPE: Parent - VALUE: DO178-2 +STATUS: Active TITLE: Strict type-safe grammar +STATEMENT: >>> +The Requirements Tool shall provide type safety for its text language. +<<< [REQUIREMENT] UID: SDOC-SSS-54 diff --git a/drafts/requirements/10_concept/11_DO178.sdoc b/drafts/requirements/20_high_level/21_DO178.sdoc similarity index 95% rename from drafts/requirements/10_concept/11_DO178.sdoc rename to drafts/requirements/20_high_level/21_DO178.sdoc index ecfcb6d82..eb532f306 100644 --- a/drafts/requirements/10_concept/11_DO178.sdoc +++ b/drafts/requirements/20_high_level/21_DO178.sdoc @@ -49,9 +49,76 @@ These requirements are recommended by engineers who adhere to the DO-178B and DO UID: SECTION-DR-Already-implemented-features TITLE: Already implemented features +[REQUIREMENT] +UID: DO178-13 +STATUS: Backlog +TITLE: Source file coverage +STATEMENT: >>> +StrictDoc shall support generation of source code coverage information. +<<< +COMMENT: >>> +S: Source file coverage is StrictDoc's experimental feature. With a more detailed specification, we can turn it to a more advanced and clear presentation of the needed aspects. +<<< + +[REQUIREMENT] +UID: DO178-12 +COMPLIANCE: C +STATUS: Backlog +TITLE: Uncovered requirement report +STATEMENT: >>> +StrictDoc shall support generation of uncovered requirement report. + +Note: An uncovered requirement is one that has no children. +<<< +COMMENT: >>> +S: This is easy to implement but would be nice to have it specified in terms of how exactly it should look like. The requirements coverage screen was one experimental attempt to visualize and highlight the uncovered requirements but we didn't stabilize the feature in terms of the visual clarity. +<<< + +[REQUIREMENT] +UID: DO178-11 +COMPLIANCE: C +STATUS: Backlog +TITLE: Impact analysis +STATEMENT: >>> +StrictDoc shall support generation of Impact Analysis information. +<<< +COMMENT: >>> +N: Impact analysis – upon modification of a requirement: report the recursive list of impacted items. +<<< +COMMENT: >>> +S: This feature is doable and a basic variant can be derived from the existing code that generates the Deep Traceability screen. A more advanced one includes a document-to-document Diff between version control revisions, including "tell me what changed between the latest commit and my changes". Based on this information, a full impact analysis package can be generated. This is less trivial to implement and requires prioritization. +<<< +COMMENT: >>> +N: For impact analysis we were thinking about some design which help to satisfy these feature: upon modification of a requirement which owns some parent links, a SHA1 of each parent requirement statement is computed and set in the edited requirement. +=> this could be captured by the GUI, and there also could exist a CLI command to perform this tagging. + +For overall analysis, a CLI command could parse the tree and compute the SHA1 and tel which requirement are to be updated because one of there ancestor were modified. +This is almost the same feature called review status in doorstop. +<<< +COMMENT: >>> +N: When adding parent links, the GUI could present a selection list of UID, with a completion filter, then compute the SHA1 of the selected parent req. +Then highlight uncovered requirement, and requirements impacted by parent change. +<<< + +[REQUIREMENT] +UID: DO178-10 +COMPLIANCE: C +STATUS: Backlog +TITLE: Traceability matrices +STATEMENT: >>> +StrictDoc shall support generation of forward and backward traceability matrices. +<<< +COMMENT: >>> +N: Trace matrix publishing (both ways : is covered by ... and covers ...) published in HTML/PDF. +<<< +COMMENT: >>> +S: This feature, especially a very basic initial one, is very easy to implement, and it is already on the nearest roadmap, see `here `_. We only need to agree on if we are on the same page about how the produced matrices look like. +<<< + [REQUIREMENT] UID: DO178-1 COMPLIANCE: C +STATUS: Active TITLE: Document concept STATEMENT: >>> StrictDoc shall store requirements in document files. @@ -65,6 +132,7 @@ An alternative implementation of "1 file per 1 requirement" can be very restrict [REQUIREMENT] UID: DO178-2 COMPLIANCE: C +STATUS: Active TITLE: Strict specified grammar STATEMENT: >>> StrictDoc shall feature a specified document grammar. @@ -76,9 +144,27 @@ COMMENT: >>> N: StrictDoc is nice. <<< +[REQUIREMENT] +UID: DO178-14 +STATUS: Active +TITLE: Requirement UID autocompletion when adding/editing parent requirements +STATEMENT: >>> +StrictDoc shall provide autocompletion feature for requirement UID identifiers. + +Note: Most immediate use case: adding/editing parent requirements. +<<< +COMMENT: >>> +N: When adding parent links, StrictDoc GUI shall present a selection list of UID, with a completion filter, then compute the sha1 of the selected parent req. +<<< +COMMENT: >>> +N: Upon req editing, a completion list of already existing reqs (+ "derived" item) would be definitely nice in Webgui ! +and would be the ultimate argument to NOT text edit. +<<< + [REQUIREMENT] UID: DO178-3 COMPLIANCE: C +STATUS: Active TITLE: Multiple git repositories document assembly STATEMENT: >>> StrictDoc shall support generating requirement trees from multiple Git repositories. @@ -90,6 +176,7 @@ N: StrictDoc is compliant. [REQUIREMENT] UID: DO178-4 COMPLIANCE: C +STATUS: Active TITLE: Document fragments in separate files STATEMENT: >>> StrictDoc shall support assembly of documents from multiple files. @@ -101,6 +188,7 @@ S: StrictDoc supports document fragments. A document fragment corresponds to a s [REQUIREMENT] UID: DO178-5 COMPLIANCE: C +STATUS: Active TITLE: PDF and HTML publishing STATEMENT: >>> StrictDoc shall support publication of documents to HTML and PDF formats. @@ -112,7 +200,7 @@ N: Sphinx is nice for release. [REQUIREMENT] UID: DO178-6 COMPLIANCE: C -STATUS: Implemented +STATUS: Active TITLE: Graphical user interface (GUI) STATEMENT: >>> StrictDoc shall support a graphical user interface. @@ -127,6 +215,7 @@ N: GUI for editing is NTH but it shall scale well to thousands of requirements. [REQUIREMENT] UID: DO178-7 COMPLIANCE: C +STATUS: Active TITLE: No use of proprietary technology STATEMENT: >>> StrictDoc shall not use any proprietary tools. @@ -139,115 +228,19 @@ S: StrictDoc is written using Python and supports the ReqIF format out of the bo <<< [REQUIREMENT] -UID: DO178-8 -TITLE: Configuration: 'Host' parameter -STATEMENT: >>> -StrictDoc shall provide an option to configure a host where a server is deployed. -<<< -COMMENT: >>> -N: Binding to any local adress (localhost) with an option would enable to edit from a smartphone bound to a raspberry server, for instance. -<<< - -[/SECTION] - -[SECTION] -UID: SECTION-DR-Nearest-roadmap -TITLE: Nearest roadmap - -[REQUIREMENT] -UID: DO178-9 -COMPLIANCE: C -TITLE: Project-level grammar -STATEMENT: >>> -StrictDoc shall support creation of a project-level grammar. -<<< -RATIONALE: >>> -A single grammar defined for a project (same grammar for several documents) helps to standardize the structure of all documents in a documentation tree and reduces the effort needed to create identical grammars all the time. -<<< -COMMENT: >>> -S: This feature is easy to implement. The easiest implementation path is to include a config parameter, such as ``project_grammar`` in the already-existing ``strictdoc.toml`` file. At startup, StrictDoc recognizes the parameter and reads the grammar from a separate file. The project grammar becomes a single source of truth for all documents in the project tree but the option to override a grammar for a given document is still preserved. -<<< - -[REQUIREMENT] -UID: DO178-10 -COMPLIANCE: C -TITLE: Traceability matrices -STATEMENT: >>> -StrictDoc shall support generation of forward and backward traceability matrices. -<<< -COMMENT: >>> -N: Trace matrix publishing (both ways : is covered by ... and covers ...) published in HTML/PDF. -<<< -COMMENT: >>> -S: This feature, especially a very basic initial one, is very easy to implement, and it is already on the nearest roadmap, see `here `_. We only need to agree on if we are on the same page about how the produced matrices look like. -<<< - -[REQUIREMENT] -UID: DO178-11 -COMPLIANCE: C -TITLE: Impact analysis -STATEMENT: >>> -StrictDoc shall support generation of Impact Analysis information. -<<< -COMMENT: >>> -N: Impact analysis – upon modification of a requirement: report the recursive list of impacted items. -<<< -COMMENT: >>> -S: This feature is doable and a basic variant can be derived from the existing code that generates the Deep Traceability screen. A more advanced one includes a document-to-document Diff between version control revisions, including "tell me what changed between the latest commit and my changes". Based on this information, a full impact analysis package can be generated. This is less trivial to implement and requires prioritization. -<<< -COMMENT: >>> -N: For impact analysis we were thinking about some design which help to satisfy these feature: upon modification of a requirement which owns some parent links, a SHA1 of each parent requirement statement is computed and set in the edited requirement. -=> this could be captured by the GUI, and there also could exist a CLI command to perform this tagging. - -For overall analysis, a CLI command could parse the tree and compute the SHA1 and tel which requirement are to be updated because one of there ancestor were modified. -This is almost the same feature called review status in doorstop. -<<< -COMMENT: >>> -N: When adding parent links, the GUI could present a selection list of UID, with a completion filter, then compute the SHA1 of the selected parent req. -Then highlight uncovered requirement, and requirements impacted by parent change. -<<< - -[REQUIREMENT] -UID: DO178-12 -COMPLIANCE: C -TITLE: Uncovered requirement report -STATEMENT: >>> -StrictDoc shall support generation of uncovered requirement report. - -Note: An uncovered requirement is one that has no children. -<<< -COMMENT: >>> -S: This is easy to implement but would be nice to have it specified in terms of how exactly it should look like. The requirements coverage screen was one experimental attempt to visualize and highlight the uncovered requirements but we didn't stabilize the feature in terms of the visual clarity. -<<< - -[REQUIREMENT] -UID: DO178-13 -TITLE: Source file coverage -STATEMENT: >>> -StrictDoc shall support generation of source code coverage information. -<<< -COMMENT: >>> -S: Source file coverage is StrictDoc's experimental feature. With a more detailed specification, we can turn it to a more advanced and clear presentation of the needed aspects. -<<< - -[REQUIREMENT] -UID: DO178-14 -TITLE: Requirement UID autocompletion when adding/editing parent requirements +UID: DO178-19 +STATUS: Active +TITLE: WYSIWYG editing STATEMENT: >>> -StrictDoc shall provide autocompletion feature for requirement UID identifiers. - -Note: Most immediate use case: adding/editing parent requirements. -<<< -COMMENT: >>> -N: When adding parent links, StrictDoc GUI shall present a selection list of UID, with a completion filter, then compute the sha1 of the selected parent req. +StrictDoc's GUI shall support a WYSIWYG test editing. <<< COMMENT: >>> -N: Upon req editing, a completion list of already existing reqs (+ "derived" item) would be definitely nice in Webgui ! -and would be the ultimate argument to NOT text edit. +Simplifies editing of formatted text. <<< [REQUIREMENT] UID: DO178-15 +STATUS: Backlog TITLE: Diff between document trees STATEMENT: >>> StrictDoc shall allow calculating Diff between two document trees. @@ -259,13 +252,14 @@ N: Highlight a req diff with its previous version (Git). <<< [REQUIREMENT] -UID: DO178-19 -TITLE: WYSIWYG editing +UID: DO178-8 +STATUS: Active +TITLE: Configuration: 'Host' parameter STATEMENT: >>> -StrictDoc's GUI shall support a WYSIWYG test editing. +StrictDoc shall provide an option to configure a host where a server is deployed. <<< COMMENT: >>> -Simplifies editing of formatted text. +N: Binding to any local address (localhost) with an option would enable to edit from a smartphone bound to a Raspberry server, for instance. <<< [/SECTION] @@ -274,9 +268,25 @@ Simplifies editing of formatted text. UID: SECTION-DR-Needs-discussion TITLE: Needs discussion +[REQUIREMENT] +UID: DO178-9 +COMPLIANCE: C +STATUS: Backlog +TITLE: Project-level grammar +STATEMENT: >>> +StrictDoc shall support creation of a project-level grammar. +<<< +RATIONALE: >>> +A single grammar defined for a project (same grammar for several documents) helps to standardize the structure of all documents in a documentation tree and reduces the effort needed to create identical grammars all the time. +<<< +COMMENT: >>> +S: This feature is easy to implement. The easiest implementation path is to include a config parameter, such as ``project_grammar`` in the already-existing ``strictdoc.toml`` file. At startup, StrictDoc recognizes the parameter and reads the grammar from a separate file. The project grammar becomes a single source of truth for all documents in the project tree but the option to override a grammar for a given document is still preserved. +<<< + [REQUIREMENT] UID: DO178-16 COMPLIANCE: PC +STATUS: Backlog TITLE: Interoperability with Sphinx STATEMENT: >>> StrictDoc shall support interoperability with Sphinx: @@ -298,6 +308,7 @@ breathe is required for the Software Design Description document which defines s [REQUIREMENT] UID: DO178-17 COMPLIANCE: NC +STATUS: Backlog TITLE: Multi-user editing of documents STATEMENT: >>> StrictDoc shall allow multi-user editing of documents. @@ -308,6 +319,7 @@ N: .sdoc file lock? [REQUIREMENT] UID: DO178-18 +STATUS: Backlog TITLE: Support for Derived requirements STATEMENT: >>> StrictDoc shall provide first-class support for Derived requirements. @@ -320,8 +332,7 @@ Two issues when a parent ref is set to ``REQUIRED: True`` in grammar: 1. I cannot specify derived requirements. 2. Top reqs do not have parents by définition. -I worked around this, using a top .sdoc with grammar parent ref optional -Including a specific requirement titled "derived" on which all other .sdoc derived reqd will point as parent ref. But this might be improved. +I worked around this, using a top .sdoc with grammar parent ref optional. Including a specific requirement titled "derived" on which all other .sdoc derived reqd will point as parent ref. But this might be improved. <<< [/SECTION] diff --git a/strictdoc/export/html/templates/screens/document/_shared/frame_toc.jinja b/strictdoc/export/html/templates/screens/document/_shared/frame_toc.jinja index 602c5834d..f1da89d90 100644 --- a/strictdoc/export/html/templates/screens/document/_shared/frame_toc.jinja +++ b/strictdoc/export/html/templates/screens/document/_shared/frame_toc.jinja @@ -8,7 +8,7 @@ class="toc" data-controller="draggable_list collapsible_list" {%- if last_moved_node_id is defined %} - data-last_moved_node_id="{{ last_moved_node_id }}" + data-last_moved_node_id="{{ last_moved_node_id.get_string_value() }}" {% endif -%} > {%- for section in document_iterator.table_of_contents() -%}