diff --git a/docs/external/needs_external.json b/docs/external/needs_external.json index cd96775..f656037 100644 --- a/docs/external/needs_external.json +++ b/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, diff --git a/docs/how-to-guides/drawio/index.rst b/docs/how-to-guides/drawio/index.rst index 1c812c5..a52f75a 100644 --- a/docs/how-to-guides/drawio/index.rst +++ b/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. diff --git a/docs/how-to-guides/external_needs/index.rst b/docs/how-to-guides/external_needs/index.rst index ae91f8b..44f2cf1 100644 --- a/docs/how-to-guides/external_needs/index.rst +++ b/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. diff --git a/docs/how-to-guides/mermaid/index.rst b/docs/how-to-guides/mermaid/index.rst index 561556b..b410dd0 100644 --- a/docs/how-to-guides/mermaid/index.rst +++ b/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. diff --git a/docs/how-to-guides/testing/index.rst b/docs/how-to-guides/testing/index.rst index 73f56be..adc485b 100644 --- a/docs/how-to-guides/testing/index.rst +++ b/docs/how-to-guides/testing/index.rst @@ -88,7 +88,7 @@ format is e.g.: .. code-block:: cpp - // @, , + // @need: , , 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"); diff --git a/docs/how-to-guides/trace-code/index.rst b/docs/how-to-guides/trace-code/index.rst index 91bea04..2029a41 100644 --- a/docs/how-to-guides/trace-code/index.rst +++ b/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** diff --git a/docs/reference/index.rst b/docs/reference/index.rst index b621778..df46600 100644 --- a/docs/reference/index.rst +++ b/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** diff --git a/docs/tutorials/plantuml-setup.rst b/docs/tutorials/plantuml-setup.rst index 6cc3a1b..a67df53 100644 --- a/docs/tutorials/plantuml-setup.rst +++ b/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 diff --git a/docs/ubproject.toml b/docs/ubproject.toml index 4c78984..ab4157a 100644 --- a/docs/ubproject.toml +++ b/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 = [ diff --git a/src/main.cpp b/src/main.cpp index eef78fa..9f867c9 100644 --- a/src/main.cpp +++ b/src/main.cpp @@ -1,6 +1,6 @@ #include -// @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; } diff --git a/src/sample1.cpp b/src/sample1.cpp index c950cb6..8fab0a4 100644 --- a/src/sample1.cpp +++ 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; diff --git a/src/sample1_unittest.cpp b/src/sample1_unittest.cpp index 2c1584a..f374099 100644 --- a/src/sample1_unittest.cpp +++ b/src/sample1_unittest.cpp @@ -73,7 +73,7 @@ namespace { // Tests Factorial(). // Tests factorial of negative numbers. -// @Test negative factorial values, T_FACT_001, test, [TS_FACTORIAL, IMPL_2] +// @need: Test negative factorial values, T_FACT_001, test, [TS_FACTORIAL, IMPL_2] TEST(FactorialTest, Negative) { // Link this test to documentation via GTest property RecordProperty("need_id", "T_FACT_001"); @@ -103,7 +103,7 @@ TEST(FactorialTest, Negative) { } // Tests factorial of 0. -// @Test factorial of zero, T_FACT_002, test, [TS_FACTORIAL, IMPL_2] +// @need: Test factorial of zero, T_FACT_002, test, [TS_FACTORIAL, IMPL_2] TEST(FactorialTest, Zero) { RecordProperty("need_id", "T_FACT_002"); RecordProperty("requirement", "REQ_MATH_001"); @@ -113,7 +113,7 @@ TEST(FactorialTest, Zero) { } // Tests factorial of positive numbers. -// @Test factorial of positive numbers, T_FACT_003, test, [TS_FACTORIAL, IMPL_2] +// @need: Test factorial of positive numbers, T_FACT_003, test, [TS_FACTORIAL, IMPL_2] TEST(FactorialTest, Positive) { RecordProperty("need_id", "T_FACT_003"); RecordProperty("requirement", "REQ_MATH_001"); @@ -128,7 +128,7 @@ TEST(FactorialTest, Positive) { // Tests IsPrime() // Tests negative input. -// @Test prime check for negative values, T_PRIME_001, test, [TS_PRIME, IMPL_3] +// @need: Test prime check for negative values, T_PRIME_001, test, [TS_PRIME, IMPL_3] TEST(IsPrimeTest, Negative) { RecordProperty("need_id", "T_PRIME_001"); RecordProperty("requirement", "REQ_MATH_002"); @@ -142,7 +142,7 @@ TEST(IsPrimeTest, Negative) { } // Tests some trivial cases. -// @Test prime check for trivial cases, T_PRIME_002, test, [TS_PRIME, IMPL_3] +// @need: Test prime check for trivial cases, T_PRIME_002, test, [TS_PRIME, IMPL_3] TEST(IsPrimeTest, Trivial) { RecordProperty("need_id", "T_PRIME_002"); RecordProperty("requirement", "REQ_MATH_002"); @@ -155,7 +155,7 @@ TEST(IsPrimeTest, Trivial) { } // Tests positive input. -// @Test prime check for positive values, T_PRIME_003, test, [TS_PRIME, IMPL_3] +// @need: Test prime check for positive values, T_PRIME_003, test, [TS_PRIME, IMPL_3] TEST(IsPrimeTest, Positive) { RecordProperty("need_id", "T_PRIME_003"); RecordProperty("requirement", "REQ_MATH_002"); diff --git a/src/sample2.cpp b/src/sample2.cpp index d0b7e9e..e78fe66 100644 --- a/src/sample2.cpp +++ b/src/sample2.cpp @@ -4,7 +4,7 @@ #include // Clones a 0-terminated C string, allocating memory using new. -// @Clone C string, IMPL_4, impl +// @need: Clone C string, IMPL_4, impl const char* MyString::CloneCString(const char* a_c_string) { if (a_c_string == nullptr) return nullptr; @@ -17,7 +17,7 @@ const char* MyString::CloneCString(const char* a_c_string) { // Sets the 0-terminated C string this MyString object // represents. -// @Set C string, IMPL_5, impl +// @need: Set C string, IMPL_5, impl void MyString::Set(const char* a_c_string) { // Makes sure this works when c_string == c_string_ const char* const temp = MyString::CloneCString(a_c_string);