From 93d2135150e0c94e018ccf5578c6a4c4e722a899 Mon Sep 17 00:00:00 2001 From: Stanislav Pankevich Date: Mon, 4 Nov 2024 18:28:07 +0100 Subject: [PATCH] backend/sdoc_source_code: C reader: recognize scope=file --- .../sphinx/source/strictdoc_01_user_guide.rst | 6 +++- .../source/strictdoc_04_release_notes.rst | 15 +++++++++ docs/strictdoc_01_user_guide.sdoc | 6 +++- docs/strictdoc_04_release_notes.sdoc | 20 ++++++++++++ .../backend/sdoc_source_code/reader_c.py | 31 ++++++++++++++++++- .../_language_parsers/c/04_c_file/file.c | 11 +++++++ .../_language_parsers/c/04_c_file/input.sdoc | 12 +++++++ .../c/04_c_file/strictdoc.toml | 7 +++++ .../_language_parsers/c/04_c_file/test.itest | 30 ++++++++++++++++++ 9 files changed, 135 insertions(+), 3 deletions(-) create mode 100644 tests/integration/features/file_traceability/_language_parsers/c/04_c_file/file.c create mode 100644 tests/integration/features/file_traceability/_language_parsers/c/04_c_file/input.sdoc create mode 100644 tests/integration/features/file_traceability/_language_parsers/c/04_c_file/strictdoc.toml create mode 100644 tests/integration/features/file_traceability/_language_parsers/c/04_c_file/test.itest diff --git a/docs/sphinx/source/strictdoc_01_user_guide.rst b/docs/sphinx/source/strictdoc_01_user_guide.rst index ab9628429..af933c7b5 100644 --- a/docs/sphinx/source/strictdoc_01_user_guide.rst +++ b/docs/sphinx/source/strictdoc_01_user_guide.rst @@ -1783,9 +1783,13 @@ To connect a source file to a requirement, a dedicated ``@relation`` marker must 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 `. +.. warning:: + + The legacy ``@sdoc`` marker is still supported by StrictDoc but is deprecated. ``@relation`` is the new correct marker name. + **1\) Linking a file to a requirement** -The marker must be added to the top comment of a file. Currently supported only in Python. +The marker must be added to the top comment of a file. .. code:: python diff --git a/docs/sphinx/source/strictdoc_04_release_notes.rst b/docs/sphinx/source/strictdoc_04_release_notes.rst index 22aaa9256..414b181b4 100644 --- a/docs/sphinx/source/strictdoc_04_release_notes.rst +++ b/docs/sphinx/source/strictdoc_04_release_notes.rst @@ -3,6 +3,21 @@ $$$$$$$$$$$$$ 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.2.0 (2024-11-XX) +============================= + +This release introduces several enhancements to the source code processing introduced in release 0.1.0. + +The backend now supports improved function tracing in C, Python, and general parsing code: + +- Forward ranges to C functions now include the top comment. +- Each range type is displayed in the output HTML. +- The C source code reader has been updated to support file-level scoping. +- The source code reader now caches parsed objects to disk, improving reading performance. +- Proper handling of functions inside nested Python classes has been implemented, allowing syntax like Foo.Bar.do_baz. Thanks to @haxtibal for contributing this enhancement. + +Additionally, caching has been centralized, and the cache directory is now configurable. The project configuration file now supports a ``cache_dir`` option, which can be set to values such as ``./output/build``. This setting can help make caching artifacts visible alongside documentation artifacts. + 0.1.0 (2024-11-01) ================== diff --git a/docs/strictdoc_01_user_guide.sdoc b/docs/strictdoc_01_user_guide.sdoc index 8cd0703c3..0ececd10c 100644 --- a/docs/strictdoc_01_user_guide.sdoc +++ b/docs/strictdoc_01_user_guide.sdoc @@ -2125,9 +2125,13 @@ To connect a source file to a requirement, a dedicated ``@relation`` marker must 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]. +.. warning:: + + The legacy ``@sdoc`` marker is still supported by StrictDoc but is deprecated. ``@relation`` is the new correct marker name. + **1\) Linking a file to a requirement** -The marker must be added to the top comment of a file. Currently supported only in Python. +The marker must be added to the top comment of a file. .. code:: python diff --git a/docs/strictdoc_04_release_notes.sdoc b/docs/strictdoc_04_release_notes.sdoc index f37d89751..ddef34788 100644 --- a/docs/strictdoc_04_release_notes.sdoc +++ b/docs/strictdoc_04_release_notes.sdoc @@ -6,6 +6,26 @@ 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.2.0 (2024-11-XX) + +[TEXT] +STATEMENT: >>> +This release introduces several enhancements to the source code processing introduced in release 0.1.0. + +The backend now supports improved function tracing in C, Python, and general parsing code: + +- Forward ranges to C functions now include the top comment. +- Each range type is displayed in the output HTML. +- The C source code reader has been updated to support file-level scoping. +- The source code reader now caches parsed objects to disk, improving reading performance. +- Proper handling of functions inside nested Python classes has been implemented, allowing syntax like Foo.Bar.do_baz. Thanks to @haxtibal for contributing this enhancement. + +Additionally, caching has been centralized, and the cache directory is now configurable. The project configuration file now supports a ``cache_dir`` option, which can be set to values such as ``./output/build``. This setting can help make caching artifacts visible alongside documentation artifacts. +<<< + +[/SECTION] + [SECTION] TITLE: 0.1.0 (2024-11-01) diff --git a/strictdoc/backend/sdoc_source_code/reader_c.py b/strictdoc/backend/sdoc_source_code/reader_c.py index d25cd26d0..899fff541 100644 --- a/strictdoc/backend/sdoc_source_code/reader_c.py +++ b/strictdoc/backend/sdoc_source_code/reader_c.py @@ -57,7 +57,36 @@ def read( nodes = traverse_tree(tree) for node_ in nodes: - if node_.type == "function_definition": + if node_.type == "translation_unit": + if ( + len(node_.children) > 0 + and node_.children[0].type == "comment" + and (comment_node := node_.children[0]) + ): + if comment_node.text is not None: + comment_text = comment_node.text.decode("utf-8") + markers = MarkerParser.parse( + comment_text, + node_.start_point[0] + 1, + # It is important that +1 is not present here because + # currently StrictDoc does not display the last empty line (\n is 10). + node_.end_point[0] + if input_buffer[-1] == 10 + else node_.end_point[0] + 1, + node_.start_point[0] + 1, + node_.start_point[1] + 1, + ) + for marker_ in markers: + if isinstance(marker_, FunctionRangeMarker) and ( + function_range_marker_ := marker_ + ): + function_range_marker_processor( + function_range_marker_, parse_context + ) + traceability_info.markers.append( + function_range_marker_ + ) + elif node_.type == "function_definition": function_name: str = "" for child_ in node_.children: diff --git a/tests/integration/features/file_traceability/_language_parsers/c/04_c_file/file.c b/tests/integration/features/file_traceability/_language_parsers/c/04_c_file/file.c new file mode 100644 index 000000000..1bcac258e --- /dev/null +++ b/tests/integration/features/file_traceability/_language_parsers/c/04_c_file/file.c @@ -0,0 +1,11 @@ +/** + * Some text. + * + * @relation(REQ-1, scope=file) + * @relation(REQ-2, scope=file) + */ +#include + +void hello_world(void) { + print("hello world\n"); +} diff --git a/tests/integration/features/file_traceability/_language_parsers/c/04_c_file/input.sdoc b/tests/integration/features/file_traceability/_language_parsers/c/04_c_file/input.sdoc new file mode 100644 index 000000000..278b98a77 --- /dev/null +++ b/tests/integration/features/file_traceability/_language_parsers/c/04_c_file/input.sdoc @@ -0,0 +1,12 @@ +[DOCUMENT] +TITLE: Hello world doc + +[REQUIREMENT] +UID: REQ-1 +TITLE: Requirement Title +STATEMENT: Requirement Statement + +[REQUIREMENT] +UID: REQ-2 +TITLE: Requirement Title #2 +STATEMENT: Requirement Statement #2 diff --git a/tests/integration/features/file_traceability/_language_parsers/c/04_c_file/strictdoc.toml b/tests/integration/features/file_traceability/_language_parsers/c/04_c_file/strictdoc.toml new file mode 100644 index 000000000..f5502ad57 --- /dev/null +++ b/tests/integration/features/file_traceability/_language_parsers/c/04_c_file/strictdoc.toml @@ -0,0 +1,7 @@ +[project] + +features = [ + "REQUIREMENT_TO_SOURCE_TRACEABILITY", + "SOURCE_FILE_LANGUAGE_PARSERS", + "PROJECT_STATISTICS_SCREEN" +] diff --git a/tests/integration/features/file_traceability/_language_parsers/c/04_c_file/test.itest b/tests/integration/features/file_traceability/_language_parsers/c/04_c_file/test.itest new file mode 100644 index 000000000..bb5e6c7fc --- /dev/null +++ b/tests/integration/features/file_traceability/_language_parsers/c/04_c_file/test.itest @@ -0,0 +1,30 @@ +REQUIRES: PYTHON_39_OR_HIGHER + +RUN: %strictdoc export %S --output-dir Output | filecheck %s --dump-input=fail +CHECK: Published: Hello world doc + +RUN: %check_exists --file "%S/Output/html/_source_files/file.c.html" + +RUN: %cat %S/Output/html/%THIS_TEST_FOLDER/input.html | filecheck %s --dump-input=fail --check-prefix CHECK-HTML +CHECK-HTML: +CHECK-HTML: file.c, lines: 1-11, the whole file + +RUN: %cat %S/Output/html/_source_files/file.c.html | filecheck %s --dump-input=fail --check-prefix CHECK-SOURCE-FILE + +CHECK-SOURCE-FILE: href="../_source_files/file.c.html#REQ-1#1#11" +CHECK-SOURCE-FILE: [ 1-11 ] file.c, the whole file + +CHECK-SOURCE-FILE: href="../_source_files/file.c.html#REQ-2#1#11" +CHECK-SOURCE-FILE: [ 1-11 ] file.c, the whole file + +CHECK-SOURCE-FILE: 
 * @relation(REQ-1, scope=file)
5
+ +RUN: %cat %S/Output/html/source_coverage.html | filecheck %s --dump-input=fail --check-prefix CHECK-SOURCE-COVERAGE +CHECK-SOURCE-COVERAGE: 100.0%