sphinx-codelinks 0.1.1__tar.gz → 0.1.2__tar.gz

{sphinx_codelinks-0.1.1 → sphinx_codelinks-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sphinx-codelinks
-Version: 0.1.1
+Version: 0.1.2
 Summary: Fast Source Code Traceability for Sphinx-Needs
 Author-email: team useblocks <info@useblocks.com>
 Maintainer-email: Marco Heinemann <marco.heinemann@useblocks.com>, Jui-Wen Chen <jui-wen.chen@useblocks.com>

{sphinx_codelinks-0.1.1 → sphinx_codelinks-0.1.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sphinx-codelinks"
-version = "0.1.1"
+version = "0.1.2"
 description = "Fast Source Code Traceability for Sphinx-Needs"
 authors = [{ name = "team useblocks", email = "info@useblocks.com" }]
 maintainers = [

{sphinx_codelinks-0.1.1 → sphinx_codelinks-0.1.2}/src/sphinx_codelinks/cmd.py

@@ -26,7 +26,7 @@ app = typer.Typer(
 
 @app.command(no_args_is_help=True)
 def discover(
-    root_dir: Annotated[
+    src_dir: Annotated[
         Path,
         typer.Argument(
             ...,
@@ -68,7 +68,7 @@ def discover(
     from sphinx_codelinks.source_discovery.source_discover import SourceDiscover
 
     source_discover = SourceDiscover(
-        root_dir=root_dir,
+        src_dir=src_dir,
         exclude=exclude,
         include=include,
         file_types=file_types,
@@ -134,8 +134,8 @@ def vdoc(
     if oneline_errors:
         errors.appendleft("Invalid oneline comment style configuration:")
         errors.extend(oneline_errors)
-
-    src_discovery_dict, src_discovery_errors = build_src_discovery_dict(project_config)
+    src_discovery_errors = []
+    src_discovery_dict = build_src_discovery_dict(project_config)
     if src_discovery_dict:
         src_discovery_config = SourceDiscoveryConfig(**src_discovery_dict)
     else:
@@ -151,9 +151,9 @@ def vdoc(
 
     from sphinx_codelinks.source_discovery.source_discover import SourceDiscover
 
-    src_root_dir = (config.parent / src_discovery_config.root_dir).resolve()
+    src_dir = (config.parent / src_discovery_config.src_dir).resolve()
     source_discover = SourceDiscover(
-        root_dir=src_root_dir,
+        src_dir=src_dir,
         exclude=src_discovery_config.exclude,
         include=src_discovery_config.include,
         file_types=src_discovery_config.file_types,
@@ -164,7 +164,7 @@ def vdoc(
 
     virtual_docs = VirtualDocs(
         src_files=source_discover.source_paths,
-        src_dir=str(src_root_dir),
+        src_dir=str(src_dir),
         output_dir=str(output_dir),
         oneline_comment_style=oneline_comment_style,
         comment_type=src_discovery_config.file_types[0]
@@ -178,7 +178,7 @@ def vdoc(
         typer.echo("The virtual documents are generated:")
         for v_doc in virtual_docs.virtual_docs:
             json_path = output_dir / v_doc.filepath.with_suffix(".json").relative_to(
-                src_root_dir
+                src_dir
             )
             typer.echo(json_path)
     else:

{sphinx_codelinks-0.1.1 → sphinx_codelinks-0.1.2}/src/sphinx_codelinks/source_discovery/config.py

@@ -6,7 +6,7 @@ from jsonschema import ValidationError, validate
 
 
 class SourceDiscoveryConfigType(TypedDict, total=False):
-    root_dir: Path
+    src_dir: Path
     exclude: list[str]
     include: list[str]
     gitignore: bool
@@ -19,8 +19,8 @@ class SourceDiscoveryConfig:
     def field_names(cls) -> set[str]:
         return {item.name for item in fields(cls)}
 
-    root_dir: Path = field(
-        default_factory=lambda: Path.cwd(), metadata={"schema": {"type": "string"}}
+    src_dir: Path = field(
+        default_factory=lambda: Path("./"), metadata={"schema": {"type": "string"}}
     )
     """The root of the source directory."""
 
@@ -41,7 +41,9 @@ class SourceDiscoveryConfig:
 
     file_types: list[str] = field(
         default_factory=lambda: ["c", "h", "cpp", "hpp"],
-        metadata={"schema": {"type": "array", "items": {"type": "string"}}},
+        metadata={
+            "schema": {"type": "array", "items": {"enum": ["c", "h", "cpp", "hpp"]}}
+        },
     )
     """The file types to discover."""
 

{sphinx_codelinks-0.1.1 → sphinx_codelinks-0.1.2}/src/sphinx_codelinks/source_discovery/source_discover.py

@@ -9,13 +9,13 @@ from gitignore_parser import parse_gitignore  # type: ignore[import-untyped]
 class SourceDiscover:
     def __init__(
         self,
-        root_dir: Path,
+        src_dir: Path,
         exclude: list[str] | None = None,
         include: list[str] | None = None,
         gitignore: bool = True,
         file_types: list[str] | None = None,
     ):
-        self.root_path = root_dir
+        self.root_path = src_dir
         self.exclude = exclude
         self.include = include
         # Only gitignore at source root is considered.

{sphinx_codelinks-0.1.1 → sphinx_codelinks-0.1.2}/src/sphinx_codelinks/sphinx_extension/config.py

@@ -43,7 +43,7 @@ class SrcTraceProjectConfigFileType(TypedDict):
 class SrcTraceProjectConfigType(TypedDict):
     # only support C/C++ for now
     comment_type: Literal["cpp", "hpp", "c", "h"]
-    src_dir: str
+    src_dir: Path
     remote_url_pattern: str
     exclude: list[str]
     include: list[str]
@@ -241,9 +241,8 @@ def check_project_configuration(config: SrcTraceSphinxConfig) -> list[str]:
     for project_name, project_config in config.projects.items():
         project_errors: list[str] = []
         oneline_errors = validate_oneline_comment_style(project_config)
-        src_discovery_dict, src_discovery_errors = build_src_discovery_dict(
-            project_config
-        )
+        src_discovery_dict = build_src_discovery_dict(project_config)
+        src_discovery_errors = []
         if src_discovery_dict is not None:
             src_discovery_config = SourceDiscoveryConfig(**src_discovery_dict)
             src_discovery_errors.extend(src_discovery_config.check_schema())
@@ -286,22 +285,40 @@ def validate_oneline_comment_style(
 
 def build_src_discovery_dict(
     project_config: SrcTraceProjectConfigType,
-) -> tuple[SourceDiscoveryConfigType | None, list[str]]:
+) -> SourceDiscoveryConfigType | None:
     src_discovery_dict = cast(SourceDiscoveryConfigType, {})
-    src_discovery_errors = []
-    if "src_dir" in project_config:
-        if isinstance(project_config["src_dir"], str):
-            src_discovery_dict["root_dir"] = Path(project_config["src_dir"])
-        else:
-            src_discovery_errors.append("src_dir must be a string")
-    for key in ("exclude", "include", "gitignore"):
+    # adapt the configs between source tracing and source discovery
+    if "comment_type" in project_config:
+        # comment type error will be taken care by SourceDiscovery class later
+        src_discovery_dict["file_types"] = (
+            list(SUPPORTED_COMMENT_TYPES)
+            if project_config["comment_type"] in SUPPORTED_COMMENT_TYPES
+            else [project_config["comment_type"]]
+        )
+    for key in ("exclude", "include", "gitignore", "src_dir"):
         if key in project_config:
             src_discovery_dict[key] = project_config[key]
-    if "comment_type" in project_config:
-        if project_config["comment_type"] not in SUPPORTED_COMMENT_TYPES:
-            src_discovery_errors.append(
-                f"comment_type must be one of {sorted(SUPPORTED_COMMENT_TYPES)}"
-            )
-        else:
-            src_discovery_dict["file_types"] = list(SUPPORTED_COMMENT_TYPES)
-    return src_discovery_dict, src_discovery_errors
+
+    return src_discovery_dict
+
+
+def adpat_src_discovery_config(project_config: SrcTraceProjectConfigType) -> None:
+    src_discovery_dict = build_src_discovery_dict(project_config)
+    if src_discovery_dict:
+        src_discovery_config = SourceDiscoveryConfig(**src_discovery_dict)
+    else:
+        src_discovery_config = SourceDiscoveryConfig()
+
+    for _field in fields(src_discovery_config):
+        key = "comment_type" if _field.name == "file_types" else _field.name
+
+        if key == "comment_type":
+            file_types = getattr(src_discovery_config, _field.name)
+            if set(file_types) == SUPPORTED_COMMENT_TYPES:
+                comment_type = "cpp"
+            else:
+                comment_type = file_types[0]
+            project_config[key] = comment_type  # type: ignore[literal-required]  # dynamically assign
+            continue
+
+        project_config[key] = getattr(src_discovery_config, _field.name)  # type: ignore[literal-required]  # dynamically assign

{sphinx_codelinks-0.1.1 → sphinx_codelinks-0.1.2}/src/sphinx_codelinks/sphinx_extension/directives/src_trace.py

@@ -1,4 +1,5 @@
 from collections.abc import Callable
+import os
 from pathlib import Path
 import subprocess
 from typing import Any, ClassVar, cast
@@ -35,13 +36,23 @@ logger = logging.getLogger(__name__)
 
 
 def generate_str_link_name(
-    comment: UBTComment, target_filepath: Path, target_dir: str
+    comment: UBTComment,
+    target_filepath: Path,
+    dirs: dict[str, Path],
+    local: bool = False,
 ) -> str:
     if comment.start_line == comment.end_line:
         lineno = f"L{comment.start_line}"
     else:
         lineno = f"L{comment.start_line}-L{comment.end_line}"
-    url = str(target_filepath.relative_to(target_dir)) + f"#{lineno}"
+    # url = str(target_filepath.relative_to(target_dir)) + f"#{lineno}"
+    if local:
+        url = str(target_filepath) + f"#{lineno}"
+    else:
+        remote_path = dirs["remote_src_dir"] / target_filepath.relative_to(
+            dirs["target_dir"]
+        )
+        url = f"{remote_path!s}#{lineno}"
 
     return url
 
@@ -151,6 +162,12 @@ class SourceTracingDirective(SphinxDirective):
         )
         needs.extend(src_trace_need)
 
+        dirs = {
+            "src_dir": src_dir,
+            "out_dir": out_dir,
+            "target_dir": target_dir,
+        }
+
         # inject needs_string_links config before add_need()
         # https://sphinx-needs.readthedocs.io/en/latest/configuration.html#needs-string-links
         # local URL
@@ -158,12 +175,13 @@ class SourceTracingDirective(SphinxDirective):
         remote_url_field = None
         if src_trace_sphinx_config.set_local_url:
             local_url_field = src_trace_sphinx_config.local_url_field
+            to_remove_str = f"{out_dir!s}{os.sep}"
+            if os.name == "nt":
+                to_remove_str = to_remove_str.replace("\\", "\\\\")
             self.env.config.needs_string_links[local_url_field] = {
                 "regex": r"^(?P<value>.+?)\.[^\.]+#L(?P<lineno>\d+)",
-                "link_url": (
-                    f"file://{target_dir!s}/{{{{value}}}}.html#L-{{{{lineno}}}}"
-                ),
-                "link_name": "{{value}}#L{{lineno}}",
+                "link_url": ("file://{{value}}.html#L-{{lineno}}"),
+                "link_name": f"{{{{value | replace('{to_remove_str}', '')}}}}#L{{{{lineno}}}}",
                 "options": [local_url_field],
             }
         if (
@@ -178,9 +196,11 @@ class SourceTracingDirective(SphinxDirective):
                 remote_src_dir = src_dir
             else:
                 remote_src_dir = src_dir.relative_to(git_root_path)
+            dirs["remote_src_dir"] = remote_src_dir
             remote_url_pattern = src_trace_conf["remote_url_pattern"].format(
                 commit=commit_id,
-                path=f"{remote_src_dir}/" + "{{value}}",
+                # path=f"{remote_src_dir}/" + "{{value}}",
+                path="{{value}}",
                 line="{{lineno}}",
             )
             self.env.config.needs_string_links[remote_url_field] = {
@@ -189,11 +209,7 @@ class SourceTracingDirective(SphinxDirective):
                 "link_name": "{{value}}#L{{lineno}}",
                 "options": [remote_url_field],
             }
-        dirs = {
-            "src_dir": src_dir,
-            "out_dir": out_dir,
-            "target_dir": target_dir,
-        }
+
         # render needs from the source files
         rendered_needs = self.render_needs(
             virtual_docs,
@@ -287,13 +303,18 @@ class SourceTracingDirective(SphinxDirective):
                 target_filepath.parent.mkdir(parents=True, exist_ok=True)
                 target_filepath.write_text(filepath.read_text())
             for comment in virtual_doc.comments:
-                # Always generate link_name to avoid unbound errors
-                link_name = None
-                if local_url_field or remote_url_field:
+                local_link_name = None
+                remote_link_name = None
+                if local_url_field:
                     # generate link name
-                    link_name = generate_str_link_name(
-                        comment, target_filepath, str(dirs["target_dir"])
+                    local_link_name = generate_str_link_name(
+                        comment, target_filepath, dirs, local=True
                     )
+                if remote_url_field:
+                    remote_link_name = generate_str_link_name(
+                        comment, target_filepath, dirs, local=False
+                    )
+
                 if comment.resolved_marker:
                     # render needs from one-line marker
                     kwargs: dict[str, str | list[str]] = {
@@ -306,12 +327,12 @@ class SourceTracingDirective(SphinxDirective):
                         ]  # title and type are mandatory for add_need()
                     }
 
-                    if local_url_field and link_name is not None:
-                        kwargs[local_url_field] = link_name
-                    if remote_url_field and link_name is not None:
-                        kwargs[remote_url_field] = link_name
+                    if local_url_field and local_link_name is not None:
+                        kwargs[local_url_field] = local_link_name
+                    if remote_url_field and remote_link_name is not None:
+                        kwargs[remote_url_field] = remote_link_name
 
-                    marker_needs: list[nodes.Node] = add_need(
+                    oneline_needs: list[nodes.Node] = 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
@@ -324,7 +345,7 @@ class SourceTracingDirective(SphinxDirective):
                         ),  # The title of the need
                         **cast(dict[str, Any], kwargs),  # type: ignore[explicit-any]
                     )
-                    rendered_needs.extend(marker_needs)
+                    rendered_needs.extend(oneline_needs)
                     if local_url_field:
                         # save the mapping of need links and line numbers of source codes
                         # for the later use in `html-collect-pages`

{sphinx_codelinks-0.1.1 → sphinx_codelinks-0.1.2}/src/sphinx_codelinks/sphinx_extension/source_tracing.py

@@ -21,6 +21,7 @@ from sphinx_codelinks.sphinx_extension.config import (
     SrcTraceConfigType,
     SrcTraceProjectConfigType,
     SrcTraceSphinxConfig,
+    adpat_src_discovery_config,
     check_configuration,
     file_lineno_href,
 )
@@ -155,6 +156,10 @@ def set_config_to_sphinx(
             for project_config in cast(
                 dict[str, SrcTraceProjectConfigType], value
             ).values():
+                # address SourceDiscovery related config
+                adpat_src_discovery_config(project_config)
+
+                # address OneLoneCommenyStyle config and its default
                 oneline_comment_style: OneLineCommentStyleType | None = cast(
                     OneLineCommentStyleType, project_config.get("oneline_comment_style")
                 )
@@ -165,6 +170,8 @@ def set_config_to_sphinx(
                             project_config["oneline_comment_style"],
                         )
                     )
+                else:
+                    project_config["oneline_comment_style"] = OneLineCommentStyle()
 
         config[f"src_trace_{key}"] = value