diff --git a/docs/_assets/StrictDoc_Architecture.drawio.png b/docs/_assets/StrictDoc_Architecture.drawio.png deleted file mode 100644 index d637a0fdc..000000000 Binary files a/docs/_assets/StrictDoc_Architecture.drawio.png and /dev/null differ diff --git a/docs/_assets/StrictDoc_Workspace-Architecture.drawio.png b/docs/_assets/StrictDoc_Workspace-Architecture.drawio.png new file mode 100644 index 000000000..0b5fba698 Binary files /dev/null and b/docs/_assets/StrictDoc_Workspace-Architecture.drawio.png differ diff --git a/docs/_assets/StrictDoc_Workspace-Roadmap.drawio.png b/docs/_assets/StrictDoc_Workspace-Roadmap.drawio.png index b73528e5f..776f2b2ad 100644 Binary files a/docs/_assets/StrictDoc_Workspace-Roadmap.drawio.png and b/docs/_assets/StrictDoc_Workspace-Roadmap.drawio.png differ diff --git a/docs/sphinx/source/_assets/StrictDoc_Workspace-Architecture.drawio.png b/docs/sphinx/source/_assets/StrictDoc_Workspace-Architecture.drawio.png new file mode 100644 index 000000000..0b5fba698 Binary files /dev/null and b/docs/sphinx/source/_assets/StrictDoc_Workspace-Architecture.drawio.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 b73528e5f..776f2b2ad 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/strictdoc_01_user_guide.rst b/docs/sphinx/source/strictdoc_01_user_guide.rst index 29c941cf7..7a9d9f047 100644 --- a/docs/sphinx/source/strictdoc_01_user_guide.rst +++ b/docs/sphinx/source/strictdoc_01_user_guide.rst @@ -13,7 +13,7 @@ Summary of StrictDoc features: - The documentation files are stored as human-readable text files. - A simple domain-specific language DSL is used for writing the documents. The text format for encoding this language is called SDoc (strict-doc). -- StrictDoc reads ``*.sdoc`` files and builds an in-memory representation of a +- StrictDoc reads \*.sdoc files and builds an in-memory representation of a document tree. - From this in-memory representation, StrictDoc can generate the documentation into a number of formats including HTML, RST, ReqIF, PDF, JSON, Excel. @@ -28,9 +28,9 @@ Summary of StrictDoc features: - Requirements to source files traceability (experimental). See :ref:`Traceability between requirements and source code `. - Custom grammar and custom fields support. The StrictDoc's grammar can be - extended to support arbitrary special fields, such as ``PRIORITY``, ``OWNER``, + extended to support arbitrary special fields, such as "PRIORITY", "OWNER", or even more specialized fields, such as - ``Automotive Safety Integrity Level (ASIL)`` or ``Verification method``. + "Automotive Safety Integrity Level (ASIL)" or "Verification method". See :ref:`Custom grammars `. - Good performance of the `textX `_ parser and parallelized incremental generation of documents: generation of @@ -1722,10 +1722,142 @@ Traceability between requirements and source code **Note:** This feature is experimental, the documentation is incomplete. -StrictDoc allows connecting requirements to source code files. Two types of -links are supported: +StrictDoc allows connecting requirements to source code files in two ways: -1\) A basic link where a requirement links to a whole file. +1. Linking source files to requirements by adding special markers in the source code without modifying the requirements. +2. Linking requirements to source files by adding relations in the requirements without altering the source code. + +The advantage of the first approach is that requirements remain agnostic to the source code and implementation details. Special markers are added solely to the source files, creating traceability back to the requirements. + +The benefit of the second approach is that traceability to source files is established without any modification to the source code. This can be useful in projects where adding markers to the source code is undesirable or not feasible. + +Both options can be used independently or in combination, depending on the project setup and allocation of software components. + +To activate the traceability to source files, configure the project config with a dedicated feature: + +.. code-block:: yaml + + [project] + + features = [ + "REQUIREMENT_TO_SOURCE_TRACEABILITY" + ] + +By default, StrictDoc looks for source files in a directory from which the ``strictdoc`` command is run. This can be changed by using the ``source_root_path`` project-level option. + +See :ref:`Project-level options ` for more details about the project-level options. + +The +`strictdoc-examples `_ +repository contains executable examples including the example of +requirements-to-source-code traceability. + +.. _SECTION-UG-Language-aware-parsing-of-source-code: + +Language-aware parsing of source code +------------------------------------- + +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. + +To activate language-aware traceability, configure the project with the following features: + +.. code:: toml + + [project] + + features = [ + "REQUIREMENT_TO_SOURCE_TRACEABILITY", + "SOURCE_FILE_LANGUAGE_PARSERS" + ] + +Currently, only Python and C parsers are implemented. Upcoming implementations include parsers for Rust, C++, Bash, and more. + +Linking source code to requirements +----------------------------------- + +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:: + + For language-specific parsing of source code, e.g., Python and C, make sure to enable the corresponding option, see :ref:`Language-aware parsing of source code `. + +**1\) Linking a file to a requirement** + +The marker must be added to the top comment of a file. Currently supported only in Python. + +.. code:: python + + """ + This file implements ... + + @relation(REQ-1, scope=file) + """ + +**2\) Linking a class to a requirement (Python only)** + +.. code:: python + + class Foo: + """ + This class implements ... + + @relation(REQ-1, scope=file) + """ + +**3\) Linking a function to a requirement (Python and C only)** + +.. code:: python + + class Foo: + def bar(self): + """ + This function implements ... + + @relation(REQ-1, scope=function) + """ + +or + +.. code:: c + + /** + * Some text. + * + * @relation(REQ-1, scope=function) + */ + void hello_world(void) { + print("Hello, World\n"); + } + +**4\) Linking a range to a requirement** + +.. code:: python + + def foo(): + # @relation(REQ-1, scope=range_start) + print("Hello, World!") + # @relation(REQ-1, scope=range_end) + +**5\) Linking a single line to a requirement** + +.. code:: python + + def foo(): + # @relation(REQ-1, scope=line) + print("Hello, World!") + +Linking requirements to source code +----------------------------------- + +The linking of requirements to source files is arranged with a special RELATION type ``File``. + +.. note:: + + For language-specific parsing of source code, e.g., Python and C, make sure to enable the corresponding option, see :ref:`Language-aware parsing of source code `. + +**1\) Linking a requirement to a whole source file** .. code-block:: text @@ -1737,53 +1869,51 @@ links are supported: TITLE: File reference STATEMENT: This requirement references the file. -2\) A range-based link where a requirement links to a file and -additionally in the file, there is a reverse link that connects a source range -back to the requirement: - -The requirement declaration contains a reference of the type ``File``: +**2\) Linking a requirement to range in a source file** .. code-block:: text [REQUIREMENT] UID: REQ-002 + TITLE: Range file reference + STATEMENT: This requirement references the file.py file. RELATIONS: - TYPE: File VALUE: file.py - TITLE: Range file reference - STATEMENT: This requirement references the file.py file. - COMMENT: >>> - If the file.py contains a source range that is connected back to this - requirement (REQ-002), the link becomes a link to the source range. - <<< - -The source file: - -.. code-block:: py + LINE_RANGE: 2, 4 - # @sdoc[REQ-002] - def hello_world(): - print("hello world") - # @sdoc[/REQ-002] +**3\) Linking a requirement to a function in a source file** -To activate the traceability to source files, configure the project config with a dedicated feature: +.. code-block:: text -.. code-block:: yaml + [REQUIREMENT] + UID: REQ-002 + TITLE: Function reference + STATEMENT: This requirement references a function in a file. + RELATIONS: + - TYPE: File + VALUE: file.py + FUNCTION: hello_world + - TYPE: File + VALUE: file.c + FUNCTION: Foo.hello_world_2 - [project] +.. note:: - features = [ - "REQUIREMENT_TO_SOURCE_TRACEABILITY" - ] + For linking to functions in classes, a class name has to be added in a format: ``.``. This is currently only supported for Python source files. -By default, StrictDoc looks for source files in a directory from which the ``strictdoc`` command is run. This can be changed by using the ``source_root_path`` project-level option. +**4\) Linking a requirement to a class in a source file (Python only)** -See :ref:`Project-level options ` for more details about the project-level options. +.. code-block:: text -The -`strictdoc-examples `_ -repository contains executable examples including the example of -requirements-to-source-code traceability. + [REQUIREMENT] + UID: REQ-002 + TITLE: Class reference + STATEMENT: This requirement references a class in a file. + RELATIONS: + - TYPE: File + VALUE: file.py + CLASS: Foo ReqIF support ============= diff --git a/docs/sphinx/source/strictdoc_02_faq.rst b/docs/sphinx/source/strictdoc_02_faq.rst index 91d598b1c..40e037d17 100644 --- a/docs/sphinx/source/strictdoc_02_faq.rst +++ b/docs/sphinx/source/strictdoc_02_faq.rst @@ -296,8 +296,6 @@ FRET has an impressive list of FRET's user interface is built with Electron. -The detailed comparison is coming. - How long has the StrictDoc project been around? =============================================== @@ -330,6 +328,8 @@ The custom RST parser was replaced with a TextX-based DSL. Since then, StrictDoc The FastAPI/Turbo/Stimulus-based Web interface prototype was created to complement the text-based interface with a graphical user interface (GUI). When the Web-based GUI is stable, StrictDoc may become useable by non-programmers too. +See also: :ref:`Project milestones `. + Which StrictDoc statistics are available? ========================================= diff --git a/docs/sphinx/source/strictdoc_03_development_plan.rst b/docs/sphinx/source/strictdoc_03_development_plan.rst index df78668f7..f15341489 100644 --- a/docs/sphinx/source/strictdoc_03_development_plan.rst +++ b/docs/sphinx/source/strictdoc_03_development_plan.rst @@ -29,6 +29,8 @@ An important feature of StrictDoc is its focus on open data, ensuring ease of da 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. +.. _SECTION-DP-Project-milestones: + Project milestones ================== @@ -84,7 +86,7 @@ As an open-source project, StrictDoc is developed without strict deadlines, howe * - 2024-Q3 - HTML2PDF improvements. ReqIF roundtrip for RELATION/ROLE. Consistent automatic escaping of Jinja templates. Passthrough->export command migration. * - 2024-Q4 - - TBD + - Connecting requirements to functions (C, Python) and classes (Python) in source code. Support the linking in both directions independently: from requirements to source using RELATION/File and from source to requirements using @relation markers. The roadmap diagram ------------------- diff --git a/docs/sphinx/source/strictdoc_04_release_notes.rst b/docs/sphinx/source/strictdoc_04_release_notes.rst index ac55b8f5a..97a2e9301 100644 --- a/docs/sphinx/source/strictdoc_04_release_notes.rst +++ b/docs/sphinx/source/strictdoc_04_release_notes.rst @@ -3,6 +3,17 @@ $$$$$$$$$$$$$ 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 `_. +Unreleased 0.1.0 (2024-11-01) +============================= + +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. +- Language-specific parsers for Python and C have been added, allowing functions (in C and Python) or classes (in Python) to be linked to requirements. +- Both forward linking of requirements to source files and backward linking of source files to requirements are supported. These features can be used independently or together within the same project. + +With this release, we are also transitioning to a more `semantic versioning `_-oriented release scheme. From now on, the MAJOR.MINOR.PATCH version components will be maintained according to the recommendations of the semantic versioning specification. + 0.0.60 (2024-10-26) =================== diff --git a/docs/sphinx/source/strictdoc_10_contributing.rst b/docs/sphinx/source/strictdoc_10_contributing.rst index 9bb13f6d9..07c89466a 100644 --- a/docs/sphinx/source/strictdoc_10_contributing.rst +++ b/docs/sphinx/source/strictdoc_10_contributing.rst @@ -22,6 +22,7 @@ following steps: single contribution. 4. If the contribution is not trivial, read through the complete development guide. +5. If the contribution is not trivial, please update the Release Notes with a high-level summary of your contribution. Refer to the release notes from previous releases for guidance on what information is desirable. How can I help? =============== diff --git a/docs/sphinx/source/strictdoc_25_design.rst b/docs/sphinx/source/strictdoc_25_design.rst index bf09dc5d3..e352558e3 100644 --- a/docs/sphinx/source/strictdoc_25_design.rst +++ b/docs/sphinx/source/strictdoc_25_design.rst @@ -55,7 +55,7 @@ High-level architecture The following diagram captures the high-level architecture of StrictDoc. -.. image:: _assets/StrictDoc_Architecture.drawio.png +.. image:: _assets/StrictDoc_Workspace-Architecture.drawio.png :alt: StrictDoc's architecture diagram :class: image :width: 100% diff --git a/docs/sphinx/source/strictdoc_30_credits.rst b/docs/sphinx/source/strictdoc_30_credits.rst index 189b40372..1a17a5989 100644 --- a/docs/sphinx/source/strictdoc_30_credits.rst +++ b/docs/sphinx/source/strictdoc_30_credits.rst @@ -19,6 +19,7 @@ The following people and organizations have contributed to StrictDoc. The contri - @BenGardiner – Import Excel feature, improvements of HTML and RST export, Document Fragments feature. - @GGBeer – Generating bibliography with BibTeX (ongoing), improvements of Excel export. +- @haxtibal – Significant improvements and bug fixes to several StrictDoc features. - @lochsh – MathJax support. - @Relasym – Important fixes of how the documents are re-generated (or not). - @stumpyfr – Improvements of Excel export. @@ -47,7 +48,9 @@ StrictDoc uses `FastAPI `_ and a combinatio StrictDoc uses `Jinja `_ as a templating engine. Jinja is used for both static HTML and RST exports as well as in the Web-based GUI. -StrictDoc uses `Pygments `_ to color-code the source files for its "requirements to source files" traceability feature. +StrictDoc uses `Pygments `_ to color-code the source files for the requirements-to-source-files traceability feature. + +StrictDoc uses `Tree-sitter `_ to enable language-aware parsing of source files for the requirements-to-source-files traceability feature. StrictDoc uses `XlsxWriter `_ and `xlrd `_ for its Excel export/import features. @@ -62,15 +65,11 @@ StrictDoc is hosted on `GitHub `_ and uses `GitHub Actions < StrictDoc's documentation is hosted on `Read the Docs `_. -Commercial IDEs by JetBrains -============================ +Free and commercial IDEs by JetBrains +===================================== -The StrictDoc's core team uses the commercial versions of +For Python development, the StrictDoc core team uses the community version of `PyCharm `_ -and -`WebStorm `_ from `JetBrains `_. -The `Licenses for Open Source Development - Community Support `_ from JetBrains are provided to the core team for free, based on the precondition that StrictDoc is developed as completely free software, without any monetization mechanisms. - -Before the license for the commercial JetBrains was obtained in 2023, the complete StrictDoc's Python codebase had been produced using `PyCharm, the Community edition `_. +In 2022-2023, the `Licenses for Open Source Development - Community Support `_ from JetBrains were provided to the core team for free, based on the precondition that StrictDoc is developed as completely free software, without any monetization mechanisms. diff --git a/docs/strictdoc_01_user_guide.sdoc b/docs/strictdoc_01_user_guide.sdoc index 4b7dadca7..e0a5bcf17 100644 --- a/docs/strictdoc_01_user_guide.sdoc +++ b/docs/strictdoc_01_user_guide.sdoc @@ -17,7 +17,7 @@ Summary of StrictDoc features: - The documentation files are stored as human-readable text files. - A simple domain-specific language DSL is used for writing the documents. The text format for encoding this language is called SDoc (strict-doc). -- StrictDoc reads ``*.sdoc`` files and builds an in-memory representation of a +- StrictDoc reads \*.sdoc files and builds an in-memory representation of a document tree. - From this in-memory representation, StrictDoc can generate the documentation into a number of formats including HTML, RST, ReqIF, PDF, JSON, Excel. @@ -32,9 +32,9 @@ Summary of StrictDoc features: - Requirements to source files traceability (experimental). See [LINK: SECTION-TRACEABILITY-REQS-TO-SOURCE-CODE]. - Custom grammar and custom fields support. The StrictDoc's grammar can be - extended to support arbitrary special fields, such as ``PRIORITY``, ``OWNER``, + extended to support arbitrary special fields, such as "PRIORITY", "OWNER", or even more specialized fields, such as - ``Automotive Safety Integrity Level (ASIL)`` or ``Verification method``. + "Automotive Safety Integrity Level (ASIL)" or "Verification method". See [LINK: SECTION-CUSTOM-GRAMMARS]. - Good performance of the `textX `_ parser and parallelized incremental generation of documents: generation of @@ -2057,10 +2057,154 @@ TITLE: Traceability between requirements and source code STATEMENT: >>> **Note:** This feature is experimental, the documentation is incomplete. -StrictDoc allows connecting requirements to source code files. Two types of -links are supported: +StrictDoc allows connecting requirements to source code files in two ways: -1\) A basic link where a requirement links to a whole file. +1. Linking source files to requirements by adding special markers in the source code without modifying the requirements. +2. Linking requirements to source files by adding relations in the requirements without altering the source code. + +The advantage of the first approach is that requirements remain agnostic to the source code and implementation details. Special markers are added solely to the source files, creating traceability back to the requirements. + +The benefit of the second approach is that traceability to source files is established without any modification to the source code. This can be useful in projects where adding markers to the source code is undesirable or not feasible. + +Both options can be used independently or in combination, depending on the project setup and allocation of software components. + +To activate the traceability to source files, configure the project config with a dedicated feature: + +.. code-block:: yaml + + [project] + + features = [ + "REQUIREMENT_TO_SOURCE_TRACEABILITY" + ] + +By default, StrictDoc looks for source files in a directory from which the ``strictdoc`` command is run. This can be changed by using the ``source_root_path`` project-level option. + +See [LINK: SDOC_UG_OPTIONS_PROJECT_LEVEL] for more details about the project-level options. + +The +`strictdoc-examples `_ +repository contains executable examples including the example of +requirements-to-source-code traceability. +<<< + +[SECTION] +UID: SECTION-UG-Language-aware-parsing-of-source-code +TITLE: Language-aware parsing of source code + +[TEXT] +STATEMENT: >>> +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. + +To activate language-aware traceability, configure the project with the following features: + +.. code:: toml + + [project] + + features = [ + "REQUIREMENT_TO_SOURCE_TRACEABILITY", + "SOURCE_FILE_LANGUAGE_PARSERS" + ] + +Currently, only Python and C parsers are implemented. Upcoming implementations include parsers for Rust, C++, Bash, and more. +<<< + +[/SECTION] + +[SECTION] +TITLE: Linking source code to requirements + +[TEXT] +STATEMENT: >>> +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:: + + For language-specific parsing of source code, e.g., Python and C, make sure to enable the corresponding option, see [LINK: SECTION-UG-Language-aware-parsing-of-source-code]. + +**1\) Linking a file to a requirement** + +The marker must be added to the top comment of a file. Currently supported only in Python. + +.. code:: python + + """ + This file implements ... + + @relation(REQ-1, scope=file) + """ + +**2\) Linking a class to a requirement (Python only)** + +.. code:: python + + class Foo: + """ + This class implements ... + + @relation(REQ-1, scope=file) + """ + +**3\) Linking a function to a requirement (Python and C only)** + +.. code:: python + + class Foo: + def bar(self): + """ + This function implements ... + + @relation(REQ-1, scope=function) + """ + +or + +.. code:: c + + /** + * Some text. + * + * @relation(REQ-1, scope=function) + */ + void hello_world(void) { + print("Hello, World\n"); + } + +**4\) Linking a range to a requirement** + +.. code:: python + + def foo(): + # @relation(REQ-1, scope=range_start) + print("Hello, World!") + # @relation(REQ-1, scope=range_end) + +**5\) Linking a single line to a requirement** + +.. code:: python + + def foo(): + # @relation(REQ-1, scope=line) + print("Hello, World!") +<<< + +[/SECTION] + +[SECTION] +TITLE: Linking requirements to source code + +[TEXT] +STATEMENT: >>> +The linking of requirements to source files is arranged with a special RELATION type ``File``. + +.. note:: + + For language-specific parsing of source code, e.g., Python and C, make sure to enable the corresponding option, see [LINK: SECTION-UG-Language-aware-parsing-of-source-code]. + +**1\) Linking a requirement to a whole source file** .. code-block:: text @@ -2072,57 +2216,57 @@ links are supported: TITLE: File reference STATEMENT: This requirement references the file. -2\) A range-based link where a requirement links to a file and -additionally in the file, there is a reverse link that connects a source range -back to the requirement: - -The requirement declaration contains a reference of the type ``File``: +**2\) Linking a requirement to range in a source file** .. code-block:: text [REQUIREMENT] UID: REQ-002 + TITLE: Range file reference + STATEMENT: This requirement references the file.py file. RELATIONS: - TYPE: File VALUE: file.py - TITLE: Range file reference - STATEMENT: This requirement references the file.py file. - COMMENT: >>> - If the file.py contains a source range that is connected back to this - requirement (REQ-002), the link becomes a link to the source range. - <<< - -The source file: + LINE_RANGE: 2, 4 -.. code-block:: py - - # @sdoc[REQ-002] - def hello_world(): - print("hello world") - # @sdoc[/REQ-002] +**3\) Linking a requirement to a function in a source file** -To activate the traceability to source files, configure the project config with a dedicated feature: +.. code-block:: text -.. code-block:: yaml + [REQUIREMENT] + UID: REQ-002 + TITLE: Function reference + STATEMENT: This requirement references a function in a file. + RELATIONS: + - TYPE: File + VALUE: file.py + FUNCTION: hello_world + - TYPE: File + VALUE: file.c + FUNCTION: Foo.hello_world_2 - [project] +.. note:: - features = [ - "REQUIREMENT_TO_SOURCE_TRACEABILITY" - ] + For linking to functions in classes, a class name has to be added in a format: ``.``. This is currently only supported for Python source files. -By default, StrictDoc looks for source files in a directory from which the ``strictdoc`` command is run. This can be changed by using the ``source_root_path`` project-level option. +**4\) Linking a requirement to a class in a source file (Python only)** -See [LINK: SDOC_UG_OPTIONS_PROJECT_LEVEL] for more details about the project-level options. +.. code-block:: text -The -`strictdoc-examples `_ -repository contains executable examples including the example of -requirements-to-source-code traceability. + [REQUIREMENT] + UID: REQ-002 + TITLE: Class reference + STATEMENT: This requirement references a class in a file. + RELATIONS: + - TYPE: File + VALUE: file.py + CLASS: Foo <<< [/SECTION] +[/SECTION] + [SECTION] TITLE: ReqIF support diff --git a/docs/strictdoc_02_faq.sdoc b/docs/strictdoc_02_faq.sdoc index f43fac823..d0b43df4a 100644 --- a/docs/strictdoc_02_faq.sdoc +++ b/docs/strictdoc_02_faq.sdoc @@ -342,8 +342,6 @@ FRET has an impressive list of `Publications `_. FRET's user interface is built with Electron. - -The detailed comparison is coming. <<< [/SECTION] @@ -383,6 +381,8 @@ The custom RST parser was replaced with a TextX-based DSL. Since then, StrictDoc **2022 – November** The FastAPI/Turbo/Stimulus-based Web interface prototype was created to complement the text-based interface with a graphical user interface (GUI). When the Web-based GUI is stable, StrictDoc may become useable by non-programmers too. + +See also: [LINK: SECTION-DP-Project-milestones]. <<< [/SECTION] diff --git a/docs/strictdoc_03_development_plan.sdoc b/docs/strictdoc_03_development_plan.sdoc index b52ffb280..66a5eddec 100644 --- a/docs/strictdoc_03_development_plan.sdoc +++ b/docs/strictdoc_03_development_plan.sdoc @@ -41,6 +41,7 @@ StrictDoc shall be compatible with other software and engineering tools. This in [/SECTION] [SECTION] +UID: SECTION-DP-Project-milestones TITLE: Project milestones [TEXT] @@ -97,7 +98,7 @@ As an open-source project, StrictDoc is developed without strict deadlines, howe * - 2024-Q3 - HTML2PDF improvements. ReqIF roundtrip for RELATION/ROLE. Consistent automatic escaping of Jinja templates. Passthrough->export command migration. * - 2024-Q4 - - TBD + - Connecting requirements to functions (C, Python) and classes (Python) in source code. Support the linking in both directions independently: from requirements to source using RELATION/File and from source to requirements using @relation markers. <<< [SECTION] diff --git a/docs/strictdoc_04_release_notes.sdoc b/docs/strictdoc_04_release_notes.sdoc index 1b0f610da..7f4c9e905 100644 --- a/docs/strictdoc_04_release_notes.sdoc +++ b/docs/strictdoc_04_release_notes.sdoc @@ -6,6 +6,22 @@ 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] +TITLE: Unreleased 0.1.0 (2024-11-01) + +[TEXT] +STATEMENT: >>> +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. +- Language-specific parsers for Python and C have been added, allowing functions (in C and Python) or classes (in Python) to be linked to requirements. +- Both forward linking of requirements to source files and backward linking of source files to requirements are supported. These features can be used independently or together within the same project. + +With this release, we are also transitioning to a more `semantic versioning `_-oriented release scheme. From now on, the MAJOR.MINOR.PATCH version components will be maintained according to the recommendations of the semantic versioning specification. +<<< + +[/SECTION] + [SECTION] TITLE: 0.0.60 (2024-10-26) diff --git a/docs/strictdoc_10_contributing.sdoc b/docs/strictdoc_10_contributing.sdoc index d04fdc3a1..b319d5301 100644 --- a/docs/strictdoc_10_contributing.sdoc +++ b/docs/strictdoc_10_contributing.sdoc @@ -27,6 +27,7 @@ following steps: single contribution. 4. If the contribution is not trivial, read through the complete development guide. +5. If the contribution is not trivial, please update the Release Notes with a high-level summary of your contribution. Refer to the release notes from previous releases for guidance on what information is desirable. <<< [/SECTION] diff --git a/docs/strictdoc_25_design.sdoc b/docs/strictdoc_25_design.sdoc index 9c6dc4119..78af9d9e6 100644 --- a/docs/strictdoc_25_design.sdoc +++ b/docs/strictdoc_25_design.sdoc @@ -71,7 +71,7 @@ TITLE: High-level architecture STATEMENT: >>> The following diagram captures the high-level architecture of StrictDoc. -.. image:: _assets/StrictDoc_Architecture.drawio.png +.. image:: _assets/StrictDoc_Workspace-Architecture.drawio.png :alt: StrictDoc's architecture diagram :class: image :width: 100% diff --git a/docs/strictdoc_30_credits.sdoc b/docs/strictdoc_30_credits.sdoc index cce43e1cd..42ea646a2 100644 --- a/docs/strictdoc_30_credits.sdoc +++ b/docs/strictdoc_30_credits.sdoc @@ -24,6 +24,7 @@ The following people and organizations have contributed to StrictDoc. The contri - @BenGardiner – Import Excel feature, improvements of HTML and RST export, Document Fragments feature. - @GGBeer – Generating bibliography with BibTeX (ongoing), improvements of Excel export. +- @haxtibal – Significant improvements and bug fixes to several StrictDoc features. - @lochsh – MathJax support. - @Relasym – Important fixes of how the documents are re-generated (or not). - @stumpyfr – Improvements of Excel export. @@ -57,7 +58,9 @@ StrictDoc uses `FastAPI `_ and a combinatio StrictDoc uses `Jinja `_ as a templating engine. Jinja is used for both static HTML and RST exports as well as in the Web-based GUI. -StrictDoc uses `Pygments `_ to color-code the source files for its "requirements to source files" traceability feature. +StrictDoc uses `Pygments `_ to color-code the source files for the requirements-to-source-files traceability feature. + +StrictDoc uses `Tree-sitter `_ to enable language-aware parsing of source files for the requirements-to-source-files traceability feature. StrictDoc uses `XlsxWriter `_ and `xlrd `_ for its Excel export/import features. @@ -81,19 +84,15 @@ StrictDoc's documentation is hosted on `Read the Docs ` [/SECTION] [SECTION] -TITLE: Commercial IDEs by JetBrains +TITLE: Free and commercial IDEs by JetBrains [TEXT] STATEMENT: >>> -The StrictDoc's core team uses the commercial versions of +For Python development, the StrictDoc core team uses the community version of `PyCharm `_ -and -`WebStorm `_ from `JetBrains `_. -The `Licenses for Open Source Development - Community Support `_ from JetBrains are provided to the core team for free, based on the precondition that StrictDoc is developed as completely free software, without any monetization mechanisms. - -Before the license for the commercial JetBrains was obtained in 2023, the complete StrictDoc's Python codebase had been produced using `PyCharm, the Community edition `_. +In 2022-2023, the `Licenses for Open Source Development - Community Support `_ from JetBrains were provided to the core team for free, based on the precondition that StrictDoc is developed as completely free software, without any monetization mechanisms. <<< [/SECTION]