diff --git a/docs/source/basics/quickstart.rst b/docs/source/basics/quickstart.rst index 7dec73c9..96893cfb 100644 --- a/docs/source/basics/quickstart.rst +++ b/docs/source/basics/quickstart.rst @@ -45,7 +45,7 @@ Directive Example ------- -.. src-trace:: dummy src +.. src-trace:: :project: src .. note:: **local-url** is not working on the website as it only supports local browse diff --git a/docs/source/components/directive.rst b/docs/source/components/directive.rst index 320393c4..f885bee5 100644 --- a/docs/source/components/directive.rst +++ b/docs/source/components/directive.rst @@ -9,7 +9,7 @@ Directive .. code-block:: rst - .. src-trace:: example_with_file + .. src-trace:: :project: project_config :file: example.cpp @@ -17,7 +17,7 @@ or .. code-block:: rst - .. src-trace:: example_with_directory + .. src-trace:: :project: project_config :directory: ./example @@ -51,15 +51,13 @@ The ``src-trace`` directive can be used with the **file** option: .. code-block:: rst - .. src-trace:: dcdc demo_1 - :id: SRC_001 + .. src-trace:: :project: dcdc :file: ./charge/demo_1.cpp The needs defined in source code are extracted and rendered to: -.. src-trace:: dcdc demo_1 - :id: SRC_001 +.. src-trace:: :project: dcdc :file: ./charge/demo_1.cpp @@ -67,15 +65,13 @@ The ``src-trace`` directive can be used with the **directory** option: .. code-block:: rst - .. src-trace:: dcdc charge - :id: SRC_001 + .. src-trace:: :project: dcdc :directory: ./discharge The needs defined in source code are extracted and rendered to: -.. src-trace:: dcdc charge - :id: SRC_002 +.. src-trace:: :project: dcdc :directory: ./discharge diff --git a/docs/source/development/change_log.rst b/docs/source/development/change_log.rst index afa2361b..c1de7791 100644 --- a/docs/source/development/change_log.rst +++ b/docs/source/development/change_log.rst @@ -8,6 +8,27 @@ Changelog Unreleased ---------- +New and Improved +................ + +- ✨ Added C# parser for ``analyse`` module. + + Need ID references and marked RST blocks can be extracted from C# source files. + The comments styles supported are:(``//``, ``/* */``, ``///``) + +- ✨ Added YAML parser for ``analyse`` module. + + Need ID references can be extracted from YAML files. + The supported comment style is ``#`` as well as inline comment style, e.g. ``key: value # comment``. + +- 👌 Directive ``src-trace`` itself does not create need items anymore and only generate need items from the one-line need definition in the given source. + + The need item is removed because: + + - It has no use cases so far. + - It creates extra need items users may not actually want in their documentation + - It creates errors with some Sphinx-Needs configurations, e.g., when ``need_id_required`` or ``needs_statuses`` is defined. + Fixes ..... @@ -40,17 +61,17 @@ New and Improved The ``write rst`` command writes a reStructuredText file with :external+needs:ref:`needextend ` directive from the extracted markers generated by ``analyse``. The generated RST can be included in the Sphinx documentation to create the source code links in the existing needs -- 🔨 Replaced ``virtual_docs`` with the new ``analyse`` module. +- 👌 Replaced ``virtual_docs`` with the new ``analyse`` module. The ``virtual_docs`` feature, which handled one-line need definitions (:ref:`OneLineCommentStyle `), has been migrated into the new ``analyse`` module and removed from the core. The caching feature of ``virtual_docs`` is temporarily removed and may be reintroduced later. -- 🔨 Updated the ``src-trace`` Sphinx directive. +- 👌 Updated the ``src-trace`` Sphinx directive. The ``src-trace`` directive now uses the new ``analyse`` API instead of the old ``virtual_docs`` one. -- 🔨 Unified configuration in TOML +- 👌 Unified configuration in TOML The configuration for ``src-trace`` directive defined in TOML is now compatible with the new ``analyse`` module. diff --git a/docs/ubproject.toml b/docs/ubproject.toml index 841fb983..a4e497b0 100644 --- a/docs/ubproject.toml +++ b/docs/ubproject.toml @@ -5,3 +5,37 @@ ignore = ["block.title_line"] [needs] id_required = true + +[parse.extend_directives.src-trace] +argument = false +options = true +content = false +content_required = false +parse_content = false +description = "A directive to generate need items from one-line definition" +extension = "sphinx-codelinks" # The extension that provides the directive + +[parse.extend_directives.video] +argument = true +content = false +options = true + +[parse.extend_directives.tabs] +argument = true +content = true +options = true + +[parse.extend_directives.typer] +argument = true +content = true +options = true + +[parse.extend_directives.button-ref] +argument = true +content = true +options = true + +[parse.extend_directives.button-link] +argument = true +content = true +options = true diff --git a/src/sphinx_codelinks/sphinx_extension/directives/src_trace.py b/src/sphinx_codelinks/sphinx_extension/directives/src_trace.py index 0e0b9412..3e46e51b 100644 --- a/src/sphinx_codelinks/sphinx_extension/directives/src_trace.py +++ b/src/sphinx_codelinks/sphinx_extension/directives/src_trace.py @@ -1,5 +1,4 @@ from collections.abc import Callable -import hashlib import os from pathlib import Path from typing import Any, ClassVar, cast @@ -8,7 +7,6 @@ from docutils.parsers.rst import directives from packaging.version import Version import sphinx -from sphinx.config import Config as _SphinxConfig from sphinx.util.docutils import SphinxDirective from sphinx_needs.api import add_need # type: ignore[import-untyped] from sphinx_needs.utils import add_doc # type: ignore[import-untyped] @@ -35,42 +33,6 @@ logger = logging.getLogger(__name__) -def _check_id( - config: _SphinxConfig, - id: str | None, - src_strings: list[str], - options: dict[str, str], - additional_options: dict[str, str], -) -> None: - """Check and set the id for the need. - - src_strings[0] is always the title. - src_strings[1] is always the project. - """ - if config.needs_id_required: - if id: - additional_options["id"] = id - else: - if "directory" in options: - src_strings.append(options["directory"]) - if "file" in options: - src_strings.append(options["file"]) - - additional_options["id"] = _make_hashed_id("SRCTRACE_", src_strings, config) - - -def _make_hashed_id( - type_prefix: str, src_strings: list[str], config: _SphinxConfig -) -> str: - """Create an ID based on the type and title of the need.""" - full_title = src_strings[0] # title is always the first element - hashable_content = "_".join(src_strings) - hashed = hashlib.sha256(hashable_content.encode("UTF-8")).hexdigest().upper() - if config.needs_id_from_title: - hashed = full_title.upper().replace(" ", "_") + "_" + hashed - return f"{type_prefix}{hashed[: config.needs_id_length]}" - - def get_rel_path(doc_path: Path, code_path: Path, base_dir: Path) -> tuple[Path, Path]: """Get the relative path from the document to the source code file and vice versa.""" doc_depth = len(doc_path.parents) - 1 @@ -114,13 +76,12 @@ class SourceTracing(nodes.General, nodes.Element): class SourceTracingDirective(SphinxDirective): - required_arguments = 1 + required_arguments = 0 optional_arguments = 0 final_argument_whitespace = True # this enables content in the directive - has_content = True + has_content = False option_spec: ClassVar[dict[str, Callable[[str], str]] | None] = { - "id": directives.unchanged_required, "project": directives.unchanged_required, "file": directives.unchanged_required, "directory": directives.unchanged_required, @@ -131,8 +92,6 @@ def run(self) -> list[nodes.Node]: validate_option(self.options) project = self.options["project"] - id = self.options.get("id") - title = self.arguments[0] # get source tracing config src_trace_sphinx_config = CodeLinksConfig.from_sphinx(self.env.config) @@ -147,12 +106,6 @@ def run(self) -> list[nodes.Node]: # the directory where the source files are copied to target_dir = out_dir / src_dir.name - additional_options = {"project": project} - - _check_id( - self.env.config, id, [title, project], self.options, additional_options - ) - source_files = self.get_src_files(self.options, src_dir, src_discover_config) # add source files into the dependency @@ -166,20 +119,6 @@ def run(self) -> list[nodes.Node]: src_analyse = SourceAnalyse(analyse_config) src_analyse.run() - needs = [] - - # create the need for src-trace directive - src_trace_need = add_need( - app=self.env.app, # The Sphinx application object - state=self.state, # The docutils state object - docname=self.env.docname, # The current document name - lineno=self.lineno, # The line number where the directive is used - need_type="srctrace", # The type of the need - title=title, # The title of the need - **additional_options, - ) - needs.extend(src_trace_need) - dirs = { "src_dir": src_dir, "out_dir": out_dir, @@ -233,14 +172,12 @@ def run(self) -> list[nodes.Node]: remote_url_field, dirs, ) - if rendered_needs: - needs.extend(rendered_needs) # for post-processing of need links # https://github.com/useblocks/sphinx-needs/issues/1210 add_doc(self.env, self.env.docname) - return needs + return rendered_needs def get_src_files( self, diff --git a/tests/__snapshots__/test_src_trace/test_build_html[sphinx_project0-source_code0].doctree.xml b/tests/__snapshots__/test_src_trace/test_build_html[sphinx_project0-source_code0].doctree.xml index da9a9f72..62f8cf8d 100644 --- a/tests/__snapshots__/test_src_trace/test_build_html[sphinx_project0-source_code0].doctree.xml +++ b/tests/__snapshots__/test_src_trace/test_build_html[sphinx_project0-source_code0].doctree.xml @@ -1,6 +1,4 @@ - - @@ -9,8 +7,6 @@ - - @@ -21,8 +17,6 @@ - - diff --git a/tests/__snapshots__/test_src_trace/test_build_html[sphinx_project1-source_code1].doctree.xml b/tests/__snapshots__/test_src_trace/test_build_html[sphinx_project1-source_code1].doctree.xml index 8fe9c487..61782970 100644 --- a/tests/__snapshots__/test_src_trace/test_build_html[sphinx_project1-source_code1].doctree.xml +++ b/tests/__snapshots__/test_src_trace/test_build_html[sphinx_project1-source_code1].doctree.xml @@ -1,6 +1,4 @@ - - diff --git a/tests/__snapshots__/test_src_trace/test_build_html[sphinx_project2-source_code2].doctree.xml b/tests/__snapshots__/test_src_trace/test_build_html[sphinx_project2-source_code2].doctree.xml index 513ce927..c3361fad 100644 --- a/tests/__snapshots__/test_src_trace/test_build_html[sphinx_project2-source_code2].doctree.xml +++ b/tests/__snapshots__/test_src_trace/test_build_html[sphinx_project2-source_code2].doctree.xml @@ -1,5 +1,3 @@ - - diff --git a/tests/__snapshots__/test_src_trace/test_build_html[sphinx_project3-source_code3].doctree.xml b/tests/__snapshots__/test_src_trace/test_build_html[sphinx_project3-source_code3].doctree.xml index 4f4c85ec..c3361fad 100644 --- a/tests/__snapshots__/test_src_trace/test_build_html[sphinx_project3-source_code3].doctree.xml +++ b/tests/__snapshots__/test_src_trace/test_build_html[sphinx_project3-source_code3].doctree.xml @@ -1,5 +1,3 @@ - - diff --git a/tests/conftest.py b/tests/conftest.py index 3930bcba..47d6f781 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -58,7 +58,7 @@ def temporary_gitignore(source_directory: Path): class DoctreeSnapshotExtension(SingleFileSnapshotExtension): _write_mode = WriteMode.TEXT - _file_extension = "doctree.xml" + file_extension = "doctree.xml" def serialize(self, data, **_kwargs): if not isinstance(data, document): @@ -84,7 +84,7 @@ def snapshot_doctree(snapshot): class AnchorsSnapshotExtension(SingleFileSnapshotExtension): _write_mode = WriteMode.TEXT - _file_extension = "anchors.json" + file_extension = "anchors.json" def serialize(self, data, **_kwargs): if not isinstance(data, list): diff --git a/tests/data/sphinx/index.rst b/tests/data/sphinx/index.rst index e0d730bb..fc47e168 100644 --- a/tests/data/sphinx/index.rst +++ b/tests/data/sphinx/index.rst @@ -1,11 +1,11 @@ -.. src-trace:: dcdc_supercharge +.. src-trace:: :project: dcdc :file: supercharge.cpp -.. src-trace:: dcdc_charge +.. src-trace:: :project: dcdc :directory: ./charge -.. src-trace:: dcdc_discharge +.. src-trace:: :project: dcdc :directory: ./discharge diff --git a/tests/doc_test/id_required/index.rst b/tests/doc_test/id_required/index.rst index 1e26a6b1..1750ff79 100644 --- a/tests/doc_test/id_required/index.rst +++ b/tests/doc_test/id_required/index.rst @@ -1,2 +1,2 @@ -.. src-trace:: dummy src +.. src-trace:: :project: src diff --git a/tests/doc_test/minimum_config/index.rst b/tests/doc_test/minimum_config/index.rst index 1e26a6b1..1750ff79 100644 --- a/tests/doc_test/minimum_config/index.rst +++ b/tests/doc_test/minimum_config/index.rst @@ -1,2 +1,2 @@ -.. src-trace:: dummy src +.. src-trace:: :project: src diff --git a/tests/doc_test/recursive_dirs/index.rst b/tests/doc_test/recursive_dirs/index.rst index 9a1dc966..36e2e061 100644 --- a/tests/doc_test/recursive_dirs/index.rst +++ b/tests/doc_test/recursive_dirs/index.rst @@ -1,2 +1,2 @@ -.. src-trace:: dummy src +.. src-trace:: :project: dummy_src