Refactor documentation and code annotations to standardize '@need:' f…

docs/external/needs_external.json

@@ -7,24 +7,18 @@
       "needs": {
         "REQ_1_1_ext": {
           "arch": {},
-          "avatar": "",
-          "closed_at": "",
-          "completion": "",
           "constraints": [],
           "constraints_passed": true,
           "constraints_results": {},
           "content": "",
-          "created_at": "",
           "docname": "page_1",
           "doctype": ".rst",
-          "duration": "",
           "external_css": "external_link",
           "external_url": null,
           "full_title": "Requirement page 1 nr 1",
           "has_dead_links": false,
           "has_forbidden_dead_links": false,
           "id": "REQ_1_1_ext",
-          "id_prefix": "",
           "is_external": false,
           "is_modified": false,
           "is_need": true,
@@ -34,56 +28,39 @@
           "lineno": 26,
           "links": [],
           "links_back": ["SPEC_1_1_ext"],
-          "max_amount": "",
-          "max_content_lines": "",
           "modifications": 0,
           "number": "1",
-          "params": "",
           "parent_need": "",
           "parent_needs": [],
           "parent_needs_back": [],
           "parts": {},
           "post_template": null,
           "pre_template": null,
-          "prefix": "",
-          "query": "",
           "section_name": "Needs",
           "sections": ["Needs", "Test Data", "Page 1"],
-          "service": "",
           "signature": "",
-          "specific": "",
           "status": "approved",
           "style": null,
           "tags": [],
           "template": null,
           "title": "Requirement page 1 nr 1",
           "type": "req",
-          "type_name": "Requirement",
-          "updated_at": "",
-          "url": "",
-          "url_postfix": "",
-          "user": ""
+          "type_name": "Requirement"
         },
         "REQ_1_2_ext": {
           "arch": {},
-          "avatar": "",
-          "closed_at": "",
-          "completion": "",
           "constraints": [],
           "constraints_passed": true,
           "constraints_results": {},
           "content": "",
-          "created_at": "",
           "docname": "page_1",
           "doctype": ".rst",
-          "duration": "",
           "external_css": "external_link",
           "external_url": null,
           "full_title": "Requirement page 1 nr 2",
           "has_dead_links": false,
           "has_forbidden_dead_links": false,
           "id": "REQ_1_2_ext",
-          "id_prefix": "",
           "is_external": false,
           "is_modified": false,
           "is_need": true,
@@ -93,56 +70,39 @@
           "lineno": 31,
           "links": [],
           "links_back": ["SPEC_1_2_ext"],
-          "max_amount": "",
-          "max_content_lines": "",
           "modifications": 0,
           "number": "2",
-          "params": "",
           "parent_need": "",
           "parent_needs": [],
           "parent_needs_back": [],
           "parts": {},
           "post_template": null,
           "pre_template": null,
-          "prefix": "",
-          "query": "",
           "section_name": "Needs",
           "sections": ["Needs", "Test Data", "Page 1"],
-          "service": "",
           "signature": "",
-          "specific": "",
           "status": "approved",
           "style": null,
           "tags": [],
           "template": null,
           "title": "Requirement page 1 nr 2",
           "type": "req",
-          "type_name": "Requirement",
-          "updated_at": "",
-          "url": "",
-          "url_postfix": "",
-          "user": ""
+          "type_name": "Requirement"
         },
         "SPEC_1_1_ext": {
           "arch": {},
-          "avatar": "",
-          "closed_at": "",
-          "completion": "",
           "constraints": [],
           "constraints_passed": true,
           "constraints_results": {},
           "content": "",
-          "created_at": "",
           "docname": "page_1",
           "doctype": ".rst",
-          "duration": "",
           "external_css": "external_link",
           "external_url": null,
           "full_title": "Specification page 1 nr 1",
           "has_dead_links": false,
           "has_forbidden_dead_links": false,
           "id": "SPEC_1_1_ext",
-          "id_prefix": "",
           "is_external": false,
           "is_modified": false,
           "is_need": true,
@@ -152,56 +112,39 @@
           "lineno": 37,
           "links": ["REQ_1_1_ext"],
           "links_back": [],
-          "max_amount": "",
-          "max_content_lines": "",
           "modifications": 0,
           "number": "1",
-          "params": "",
           "parent_need": "",
           "parent_needs": [],
           "parent_needs_back": [],
           "parts": {},
           "post_template": null,
           "pre_template": null,
-          "prefix": "",
-          "query": "",
           "section_name": "Needs",
           "sections": ["Needs", "Test Data", "Page 1"],
-          "service": "",
           "signature": "",
-          "specific": "",
           "status": null,
           "style": null,
           "tags": [],
           "template": null,
           "title": "Specification page 1 nr 1",
           "type": "spec",
-          "type_name": "Specification",
-          "updated_at": "",
-          "url": "",
-          "url_postfix": "",
-          "user": ""
+          "type_name": "Specification"
         },
         "SPEC_1_2_ext": {
           "arch": {},
-          "avatar": "",
-          "closed_at": "",
-          "completion": "",
           "constraints": [],
           "constraints_passed": true,
           "constraints_results": {},
           "content": "",
-          "created_at": "",
           "docname": "page_1",
           "doctype": ".rst",
-          "duration": "",
           "external_css": "external_link",
           "external_url": null,
           "full_title": "Specification page 1 nr 2",
           "has_dead_links": false,
           "has_forbidden_dead_links": false,
           "id": "SPEC_1_2_ext",
-          "id_prefix": "",
           "is_external": false,
           "is_modified": false,
           "is_need": true,
@@ -211,35 +154,24 @@
           "lineno": 42,
           "links": ["REQ_1_2_ext"],
           "links_back": [],
-          "max_amount": "",
-          "max_content_lines": "",
           "modifications": 0,
           "number": "2",
-          "params": "",
           "parent_need": "",
           "parent_needs": [],
           "parent_needs_back": [],
           "parts": {},
           "post_template": null,
           "pre_template": null,
-          "prefix": "",
-          "query": "",
           "section_name": "Needs",
           "sections": ["Needs", "Test Data", "Page 1"],
-          "service": "",
           "signature": "",
-          "specific": "",
           "status": null,
           "style": null,
           "tags": [],
           "template": null,
           "title": "Specification page 1 nr 2",
           "type": "spec",
-          "type_name": "Specification",
-          "updated_at": "",
-          "url": "",
-          "url_postfix": "",
-          "user": ""
+          "type_name": "Specification"
         }
       },
       "needs_amount": 4,

docs/how-to-guides/drawio/index.rst

@@ -1,7 +1,7 @@
 .. _drawio-integration:
 
-:octicon:`apps` Draw.io Integration
-====================================
+:octicon:`workflow` Draw.io Integration
+=======================================
 
 Draw.io (diagrams.net) is a powerful, free diagramming tool that can be used to create various types of diagrams including flowcharts, network diagrams, UML diagrams, and more. This guide shows how to integrate Draw.io diagrams into your Sphinx documentation.
 

docs/how-to-guides/external_needs/index.rst

@@ -1,7 +1,7 @@
 .. _external-needs:
 
-:octicon:`log` How to integrate External Needs
-==============================================
+:octicon:`link-external` How to integrate External Needs
+========================================================
 
 Sometimes you want to integrate needs from an external source into your documentation.
 A known and valid use-case might be for example the integration of "plattform" requirements.

docs/how-to-guides/mermaid/index.rst

@@ -1,7 +1,7 @@
 .. _mermaid-integration:
 
-:octicon:`apps` Mermaid Integration
-===================================
+:octicon:`code-square` Mermaid Integration
+==========================================
 
 Mermaid is a popular tool for creating diagrams and visualizations using a simple markdown-like syntax. It is often used in documentation to illustrate concepts, workflows, and architectures.
 

docs/how-to-guides/testing/index.rst

@@ -88,7 +88,7 @@ format is e.g.:
 
 .. code-block:: cpp
 
-   // @<description>, <need_id>, <need_type>
+   // @need: <description>, <need_id>, <need_type>
    TEST(TestSuite, TestName) {
        // test implementation
    }
@@ -100,7 +100,7 @@ Example from ``sample1_unittest.cpp``:
    :lines: 76-88
    :caption: Annotated test case with GTest properties
 
-The annotation ``@Test negative factorial values, T_FACT_001, test``
+The annotation ``@need: Test negative factorial values, T_FACT_001, test``
 creates a traceable link between the test code and the documentation.
 
 **GTest Properties** (``RecordProperty``):
@@ -117,12 +117,12 @@ Step 3: Link Test Cases to Specifications
 -----------------------------------------
 
 Test cases are automatically discovered from source code using
-sphinx-codelinks. The test files contain ``@`` annotations that define
+sphinx-codelinks. The test files contain ``@need:`` annotations that define
 test needs:
 
 .. code-block:: cpp
 
-   // @Test negative factorial values, T_FACT_001, test
+   // @need: Test negative factorial values, T_FACT_001, test
    TEST(FactorialTest, Negative) {
      RecordProperty("need_id", "T_FACT_001");
      RecordProperty("requirement", "REQ_MATH_001");

docs/how-to-guides/trace-code/index.rst

@@ -18,7 +18,7 @@ Add a ``[codelinks]`` section to your ``ubproject.toml`` (next to
 .. literalinclude:: ../../ubproject.toml
    :language: toml
    :caption: ubproject.toml (codelinks section)
-   :start-at: "[codelinks]"
+   :start-at: [codelinks]
 
 **Step 3: Add the src-trace Directive**
 

docs/reference/index.rst

@@ -1,6 +1,6 @@
 .. _reference:
 
-:octicon:`file-symlink-file` Reference
+:octicon:`book` Reference
 ======================================
 
 A curated collection of tools, libraries, and resources for **X-as-Code**

docs/tutorials/plantuml-setup.rst

@@ -1,7 +1,7 @@
 .. _tutorial-plantuml-setup:
 
-:octicon:`image` Setting Up PlantUML for Sphinx-Needs
-=====================================================
+:octicon:`file-code` Setting Up PlantUML for Sphinx-Needs
+=========================================================
 
 This tutorial guides you through setting up PlantUML to unlock
 advanced diagram capabilities in sphinx-needs. By the end, you'll be

docs/ubproject.toml

@@ -11,7 +11,9 @@
 [project]
 name = "X-as-Code (XaC)"
 description = "Showcases for working with Sphinx-Needs"
-srcdir = "."
+
+[source]
+dir = "."
 
 # Rules for the ubCode formater, to get a nice looking documentation.
 [format_rst]
@@ -380,16 +382,6 @@ content = true
 content_required = true
 options = false
 
-[parse.extend_directives.button-link]
-# see https://sphinx-design.readthedocs.io/en/latest/badges_buttons.html#buttons
-# not yet part of ubCode internal directives
-description = "Sphinx-Design button with link"
-argument = true
-argument_required = true
-content = true
-content_required = true
-options = true
-
 # see https://sphinx-needs.readthedocs.io/en/latest/configuration.html#needs-import-keys
 [needs.import_keys]
 imported_project = "/needs_import.json"
@@ -427,10 +419,9 @@ comment_type = "cpp"
 [codelinks.projects.x-as-code-cpp.analyse]
 get_need_id_refs = true
 get_oneline_needs = true
-get_rst = true
 
 [codelinks.projects.x-as-code-cpp.analyse.oneline_comment_style]
-# start_sequence = "@"
+start_sequence = "@need:"
 # end_sequence for the online comments; default is an os-dependant newline character
 field_split_char = ","
 needs_fields = [

src/main.cpp

@@ -1,6 +1,6 @@
 #include <iostream>
 
-// @Adding two integers, IMPL_1, impl, [REQ_0815]
+// @need: Adding two integers, IMPL_1, impl, [REQ_0815]
 int add(int a, int b) {
     return a + b;
 }

src/sample1.cpp

@@ -1,7 +1,7 @@
 #include "sample1.h"
 
 // Returns n! (the factorial of n).  For negative n, n! is defined to be 1.
-// @Calculate Factorial, IMPL_2, impl
+// @need: Calculate Factorial, IMPL_2, impl
 int Factorial(int n) {
   int result = 1;
   for (int i = 1; i <= n; i++) {
@@ -12,7 +12,7 @@ int Factorial(int n) {
 }
 
 // Returns true if and only if n is a prime number.
-// @Check if prime, IMPL_3, impl
+// @need: Check if prime, IMPL_3, impl
 bool IsPrime(int n) {
   // Trivial case 1: small numbers
   if (n <= 1) return false;