docs: update release notes, roadmap, document Doxygen tagfile

Author: stanislaw

docs/_assets/StrictDoc_Workspace-Roadmap.drawio.png

@@ -1862,93 +1862,6 @@ 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::
-
-    [project]
-
-    features = [
-      "SEARCH"
-    ]
-
-The web interface includes the Search screen, designed for conducting queries against a document tree. The command-line interface supports filtering of requirements and sections through the ``export`` commands.
-
-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:
-
-- Every query component shall start with ``node.``.
-- ``and`` and ``or`` expressions must be grouped using round brackets.
-- Only double quotes are accepted for strings.
-
-.. list-table:: Query examples
-   :widths: 50 50
-   :header-rows: 1
-
-   * - **Query**
-     - **Description**
-
-   * - ``node.is_requirement``
-     - Find all requirements.
-
-   * - ``node.is_section``
-     - Find all sections.
-
-   * - ``node.is_root``
-     - Find all requirements or sections from documents with ``ROOT: True``. See :ref:`Document <SECTION-UG-Document>` for the description of the ``ROOT`` option.
-
-   * - ``(node.is_requirement and "System" in node["TITLE"])``
-     - Find all requirements with a TITLE that equals to "System".
-
-   * - ``(node.is_requirement and node.has_parent_requirements)``
-     - Find all requirements which have parent requirements.
-
-   * - ``(node.is_requirement and node.has_child_requirements)``
-     - Find all requirements which have child requirements.
-
-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.
-
-Example:
-
-.. code-block::
-
-    strictdoc export . --filter-requirements '"System" in node["TITLE"]'
-
 Markup
 ======
 
@@ -2225,8 +2138,6 @@ Traceability between requirements and source code
     * - **MID:**
       - 4398b17f61ad4dd290e72d7888597f48
 
-**Note:** This feature is experimental, the documentation is incomplete.
-
 StrictDoc allows connecting requirements to source code files in two ways:
 
 1. Linking source files to requirements by adding special markers in the source code without modifying the requirements.
@@ -2284,7 +2195,7 @@ To activate language-aware traceability, configure the project with the followin
       "SOURCE_FILE_LANGUAGE_PARSERS"
     ]
 
-Currently, only Python and C parsers are implemented. Upcoming implementations include parsers for Rust, C++, Bash, and more.
+Currently, only Python and C/C++ parsers are implemented. Upcoming implementations include parsers for Rust, Bash, and more.
 
 Linking source code to requirements
 -----------------------------------
@@ -2296,7 +2207,7 @@ Linking source code to requirements
     * - **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.
+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. The marker supports both () and {} for arguments.
 
 .. note::
 
@@ -2306,6 +2217,8 @@ To connect a source file to a requirement, a dedicated ``@relation`` marker must
 
     The legacy ``@sdoc`` marker is still supported by StrictDoc but is deprecated. ``@relation`` is the new correct marker name.
 
+It is also possible to use @relation markers and be compatible with Doxygen. See :ref:`Doxygen <SECTION-UG-Doxygen>`.
+
 **1\) Linking a file to a requirement**
 
 The marker must be added to the top comment of a file.
@@ -2329,7 +2242,7 @@ The marker must be added to the top comment of a file.
         @relation(REQ-1, scope=class)
         """
 
-**3\) Linking a function to a requirement (Python and C only)**
+**3\) Linking a function to a requirement (Python, C, and C++ only)**
 
 .. code:: python
 
@@ -2354,6 +2267,10 @@ or
         print("Hello, World\n");
     }
 
+.. note::
+
+    For the C and C++ languages, if a ``@relation`` marker is included in a function declaration prototype (which is the most common practice), StrictDoc also creates a link between the requirement and the corresponding C function definition.
+
 **4\) Linking a range to a requirement**
 
 .. code:: python
@@ -3061,6 +2978,72 @@ The following is a list of features that are considered less portable when it co
 
     It is easier to extend StrictDoc to produce a format supported by a given tool than it is to make the other tool export a 100%-identical content back to StrictDoc. If there is a need to interface with a tool X and something is missing in StrictDoc, please reach out to the developers (see :ref:`Contact the developers <SDOC_UG_CONTACT>`).
 
+Interoperability with other tools
+=================================
+
+.. _SECTION-UG-Doxygen:
+
+Doxygen
+-------
+
+.. list-table::
+    :align: left
+    :header-rows: 0
+
+    * - **MID:**
+      - a8664547ac7e41399d7d8d263869abc6
+
+HTML documentation generated by StrictDoc can be integrated with Doxygen documentation.
+
+Doxygen includes a ``TAGFILE`` feature that allows linking to external documentation. This tagfile is in XML format and looks like this:
+
+.. code::
+
+    <?xml version='1.0' encoding='UTF-8' standalone='yes' ?>
+    <tagfile doxygen_version="1.9.8">
+      <compound kind="file">
+        <name>REQ-1</name>
+        <filename>strictdocfolder/mystrictdocreq.html#REQ-1</filename>
+      </compound>
+    </tagfile>
+
+StrictDoc automatically generates a Doxygen tagfile containing the requirements using the export command:
+
+.. code::
+
+    strictdoc export . --formats=html,doxygen
+
+When a requirement is referenced in a source code comment block with the command ``\ref REQ-1``, Doxygen includes a link to the corresponding ``<filename/>`` in the output.
+
+The location of the StrictDoc export can be specified in the TAGFILE field, either as a relative path, e.g., ``TAGFILES = strictdoc.tag=../../strictdoc``, or as an absolute URL, e.g., ``TAGFILES = strictdoc.tag=http://example.com/strictdoc``.
+
+To make the StrictDoc @relation keyword work with Doxygen, an alias has to be created:
+
+.. code::
+
+    ALIASES  += relation{2}="\ref \1"
+
+resulting in the following syntax to be recognized by Doxygen: ``@relation{REQ-1, scope=function}``.
+
+Relevant Doxygen documentation:
+
+- `Linking to external documentation <https://www.doxygen.nl/manual/external.html>`_
+- `TAGFILES <https://www.doxygen.nl/manual/config.html#cfg_tagfiles>`_
+
+Valispace
+---------
+
+.. list-table::
+    :align: left
+    :header-rows: 0
+
+    * - **MID:**
+      - 5fe39dedfa4640d2bd7127ff23b0e3de
+
+Valispace provides a Python API, including an example script for exporting all project requirements in JSON format. See `Examples: Get a complete project requirements tree <https://github.com/valispace/ValispacePythonAPI/pull/22>`_.
+
+The ``GetAllProjectRequirementsTree.py`` script can be used to create a converter that generates SDoc text files customized to the specifics of the project.
+
 .. _SDOC_UG_EXPERIMENTAL_FEATURES:
 
 Experimental features
@@ -3079,6 +3062,93 @@ A feature is considered stable when all its known edge cases have been covered a
 
 See also :ref:`Selecting features <SDOC_UG_CONFIG_FEATURES>` for general instructions.
 
+.. _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::
+
+    [project]
+
+    features = [
+      "SEARCH"
+    ]
+
+The web interface includes the Search screen, designed for conducting queries against a document tree. The command-line interface supports filtering of requirements and sections through the ``export`` commands.
+
+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:
+
+- Every query component shall start with ``node.``.
+- ``and`` and ``or`` expressions must be grouped using round brackets.
+- Only double quotes are accepted for strings.
+
+.. list-table:: Query examples
+   :widths: 50 50
+   :header-rows: 1
+
+   * - **Query**
+     - **Description**
+
+   * - ``node.is_requirement``
+     - Find all requirements.
+
+   * - ``node.is_section``
+     - Find all sections.
+
+   * - ``node.is_root``
+     - Find all requirements or sections from documents with ``ROOT: True``. See :ref:`Document <SECTION-UG-Document>` for the description of the ``ROOT`` option.
+
+   * - ``(node.is_requirement and "System" in node["TITLE"])``
+     - Find all requirements with a TITLE that equals to "System".
+
+   * - ``(node.is_requirement and node.has_parent_requirements)``
+     - Find all requirements which have parent requirements.
+
+   * - ``(node.is_requirement and node.has_child_requirements)``
+     - Find all requirements which have child requirements.
+
+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.
+
+Example:
+
+.. code-block::
+
+    strictdoc export . --filter-requirements '"System" in node["TITLE"]'
+
 .. _SECTION-UG-Project-statistics-screen:
 
 Project statistics screen

docs/sphinx/source/_assets/StrictDoc_Workspace-Roadmap.drawio.png

@@ -195,7 +195,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 <https://github.com/strictdoc-project/strictdoc/blob/main/docs/strictdoc_02_faq.sdoc>`_
+`strictdoc_03_faq <https://github.com/strictdoc-project/strictdoc/blob/main/docs/strictdoc_03_faq.sdoc>`_
 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:

docs/sphinx/source/strictdoc_01_user_guide.rst

@@ -8,7 +8,39 @@ $$$$$$$$$$$$$
     * - **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 <https://github.com/strictdoc-project/strictdoc/blob/main/CHANGELOG.md>`_.
+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 as GitHub releases: `StrictDoc Releases <https://github.com/strictdoc-project/strictdoc/releases>`_.
+
+Unreleased (2024-11-XX)
+=======================
+
+.. list-table::
+    :align: left
+    :header-rows: 0
+
+    * - **MID:**
+      - f4e63483a11b442993c47b5d0574e89b
+
+This release introduces language-aware tracing between requirements and C++ source code.
+
+Currently, only C++ functions can be traced using a marker like ``@relation(REQ-1, scope=function)``. The ability to add markers to classes has not yet been implemented.
+
+A new export format has been added to generate a Doxygen tagfile for a documentation tree. When the tagfile is registered in the Doxygen configuration, requirements can be referenced using Doxygen keywords. For example: ``\relation{REQ-1, scope=function}``. Special thanks to @johanenglund for contributing the idea and helping to implement the solution.
+
+Additionally, a minor HTML2PDF formatting issue has been resolved. Previously, RST admonitions were not rendered correctly when spanning across two pages.
+
+0.3.0 (2024-11-21)
+==================
+
+.. list-table::
+    :align: left
+    :header-rows: 0
+
+    * - **MID:**
+      - b39a3b3d9f8640e380dad5a2fdb75d79
+
+This release includes an enhancement to the feature for tracing requirements to C source code.
+
+From now on, if a ``@relation`` marker is specified in a C function declaration, StrictDoc will perform its "magic" and automatically connect the referenced requirement to the corresponding C function definition. This allows a ``@relation`` marker to be placed in the main documentation block, typically located above C function declarations, while ensuring the requirement is also linked to the function definition.
 
 0.2.1 (2024-11-10)
 ==================

docs/sphinx/source/strictdoc_03_faq.rst

@@ -143,16 +143,18 @@ Python code
   raised when it is consistently deprecated by major software platforms like
   Ubuntu or GitHub Actions.
 
-- All developer tasks are collected in the ``tasks.py`` which is run by Invoke
-  tool. Run the ``invoke --list`` command to see the list of available commands.
+- All developer tasks are collected in the ``tasks.py`` which is run by Invoke tool. Run the ``invoke --list`` command to see the list of available commands.
 
 - Formatting is governed by ``black`` which reformats the code automatically
   when the ``invoke check`` command is run.
 
   - If a string literal gets too long, it should be split into a multiline
     literal with each line being a meaningful word or a subsentence.
 
-- For "element is non-None" checks, a full form shall be used, for example: ``if foo is not None`` instead of ``if foo``. This helps to avoid any confusion with all sorts of strings (empty or non-empty ``str``, ``Optional[str]``) that are used extensively in StrictDoc's codebase. The non-None and non-empty string check shall therefore be as follows: ``if foo is not None and len(foo) > 0``. The explicit check also applies to any other kinds of objects besides strings: ``if foo is not None`` instead of ``if foo``. Rationale: ``if foo`` makes it unclear whether the intention is to check `is not None` or also ``len(foo) > 0``.
+- Avoid shortening variable names unnecessarily. For example, use 'buffer' instead of 'buf', 'document' instead of 'doc', 'function' instead of 'func', 'length' instead of 'len', etc. Note: While some older parts of StrictDoc may not adhere to this guideline, they are planned to be refactored in the future.
+
+- For "element is non-None" checks, a full form shall be used, for example: ``if foo is not None`` instead of ``if foo``. This helps to avoid any confusion with all sorts of strings (empty or non-empty ``str``, ``Optional[str]``) that are used extensively in StrictDoc's codebase. The non-None and non-empty string check shall therefore be as follows: ``if foo is not None and len(foo) > 0``. The explicit check also applies to any other kinds of objects besides strings: ``if foo is not None`` instead of ``if foo``. Rationale: ``if foo`` makes it unclear whether the intention is to check ``is not None`` or also ``len(foo) > 0``.
+
 - For lambdas and short for loops, the recent convention is to add ``_`` to the variables of a for loop or a lambda to visually highlight their temporary use within the current scope which is done to counter the fact that these variables can leak and be used outside of the scope of the loop. Example:
 
 .. code-block:: python
@@ -161,7 +163,9 @@ Python code
         # use a_, b_ within the loop.
 
 - The function arguments with the default values shall be avoided. This convention improves the visibility of the function interfaces at the coast of increased verbosity which is the price that StrictDoc development is willing to pay, maintaining the software long-term. The all-explicit function parameters indication is especially useful when the large code refactorings are made.
+
 - StrictDoc has been making a gradual shift towards a stronger type system. Although type annotations haven't been added everywhere in the codebase, it is preferred to include them for all new code that is written.
+
 - If a contribution includes changes in StrictDoc's code, at least the
   integration-level tests should be added to the ``tests/integration``. If the
   contributed code needs a fine-grained control over the added behavior, adding