add CLI for needextend bridge

Author: juiwenchen

src/sphinx_codelinks/cmd.py

@@ -4,7 +4,7 @@
 from os import linesep
 from pathlib import Path
 import tomllib
-from typing import Annotated, cast
+from typing import Annotated, TypeAlias, cast
 
 import typer
 
@@ -22,6 +22,8 @@
     SourceAnalyseConfigType,
     SrcDiscoverConfigType4Analyse,
 )
+from sphinx_codelinks.logger import logger
+from sphinx_codelinks.needextend_bridge import convert_marked_content
 from sphinx_codelinks.source_discover.config import (
     SourceDiscoverConfig,
     SourceDiscoverConfigType,
@@ -34,6 +36,30 @@
 )
 
 
+OptVerbose: TypeAlias = Annotated[  # noqa: UP040   # has to be TypeAlias
+    bool,
+    typer.Option(
+        ...,
+        "-v",
+        "--verbose",
+        is_flag=True,
+        help="Show debug information",
+        rich_help_panel="Logging",
+    ),
+]
+OptQuiet: TypeAlias = Annotated[  # noqa: UP040 # has to be TypeAlias
+    bool,
+    typer.Option(
+        ...,
+        "-q",
+        "--quiet",
+        is_flag=True,
+        help="Only show errors and warnings",
+        rich_help_panel="Logging",
+    ),
+]
+
+
 @app.command(no_args_is_help=True)
 def analyse(
     config: Annotated[
@@ -212,6 +238,49 @@ def discover(
         typer.echo(file_path)
 
 
+@app.command(no_args_is_help=True)
+def bridge(
+    jsonpath: Annotated[
+        Path,
+        typer.Argument(
+            ...,
+            help="Path of the JSON file which contains the extracted markers",
+            show_default=False,
+            dir_okay=False,
+            file_okay=True,
+            exists=True,
+            resolve_path=True,
+        ),
+    ],
+    outdir: Annotated[
+        Path,
+        typer.Option(
+            "--outdir",
+            "-o",
+            help="The output directory for needextend.rst",
+            show_default=True,
+            dir_okay=True,
+            file_okay=False,
+            exists=True,
+        ),
+    ] = Path.cwd(),  # noqa: B008  # to show default value in this CLI
+    remote_url_field: Annotated[
+        str,
+        typer.Option(
+            "--remote-url-field",
+            "-r",
+            help="The field name for the remote url",
+            show_default=True,
+        ),
+    ] = "remote_url",  # to show default value in this CLI
+    verbose: OptVerbose = False,
+    quiet: OptQuiet = False,
+) -> None:
+    """Generate needextend.rst from the extracted obj in JSON."""
+    logger.configure(verbose, quiet)
+    convert_marked_content(jsonpath, outdir, remote_url_field)
+
+
 def load_config_from_toml(
     toml_file: Path, project: str | None = None
 ) -> SrcTraceProjectConfigFileType:

src/sphinx_codelinks/bridge.py src/sphinx_codelinks/needextend_bridge.pysrc/sphinx_codelinks/bridge.py renamed to src/sphinx_codelinks/needextend_bridge.py

@@ -40,19 +40,31 @@ def field_names(cls) -> set[str]:
             "schema": {
                 "type": "object",
                 "properties": {
-                    "row": {"type": "integer"},
-                    "column": {"type": "integer"},
+                    "start": {
+                        "type": "object",
+                        "properties": {
+                            "row": {"type": "integer"},
+                            "column": {"type": "integer"},
+                        },
+                        "required": ["row", "column"],
+                    },
+                    "end": {
+                        "type": "object",
+                        "properties": {
+                            "row": {"type": "integer"},
+                            "column": {"type": "integer"},
+                        },
+                        "required": ["row", "column"],
+                    },
                 },
-                "required": ["row", "column"],
+                "required": ["start", "end"],
                 "additionalProperties": False,
             }
         }
     )
     """Coordinate of the marked content in a file"""
 
-    tagged_scope: str | None = field(
-        metadata={"schema": {"type": "string", "nullable": True}}
-    )
+    tagged_scope: str | None = field(metadata={"schema": {"type": ["string", "null"]}})
     """The scoped tagged by the marked content"""
 
     type: MarkedContentType = field(
@@ -66,20 +78,20 @@ def field_names(cls) -> set[str]:
     """Type of the marked content."""
 
     marker: str | None = field(
-        default=None, metadata={"schema": {"type": "string", "nullable": True}}
+        default=None, metadata={"schema": {"type": ["string", "null"]}}
     )
     """Marker of the marked content."""
 
     need_ids: list[str] | None = field(
         default=None,
-        metadata={"schema": {"type": "array", "items": {"type": "string"}}},
+        metadata={"schema": {"type": ["array", "null"], "items": {"type": "string"}}},
     )
     """Need id refs which is associated to the need items in the documentation."""
     need: dict[str, str | list[str]] | None = field(
         default=None,
         metadata={
             "schema": {
-                "type": "object",
+                "type": ["object", "null"],
                 "properties": {"title": {"type": "string"}, "id": {"title": "string"}},
                 "required": ["title", "id"],
                 "additionalProperties": True,
@@ -89,7 +101,7 @@ def field_names(cls) -> set[str]:
     """Definition of a need item"""
 
     rst: str | None = field(
-        default=None, metadata={"schema": {"type": "string", "nullable": True}}
+        default=None, metadata={"schema": {"type": ["string", "null"]}}
     )
     """Extracted rst text."""
 
@@ -151,7 +163,7 @@ class MarkedObjType(TypedDict):
     rst: str | None
 
 
-def convert_makred_content(
+def convert_marked_content(
     jsonpath: Path, outdir: Path, remote_url_field: str = "remote_url"
 ) -> None:
     """Convert marked objects extracted by anaylse CLI to needextend in RST"""
@@ -172,7 +184,7 @@ def convert_makred_content(
         obj_warnings.extend(schema.check_schema())
         obj_warnings.extend(schema.check_conditional_required_fields())
         if obj_warnings:
-            obj_warnings.appendleft(f"Marked object {obj} has the following warnings:")
+            obj_warnings.appendleft(f"{obj} has the following warnings:")
             warnings.extend(list(obj_warnings))
 
     if warnings:
@@ -193,3 +205,5 @@ def convert_makred_content(
     needextend_path = outdir / "needextend.rst"
     with needextend_path.open("w") as f:
         f.writelines(needextend_texts)
+
+    logger.info(f"Generated needextend.rst in {needextend_path}")

tests/test_bridge.py

@@ -1,8 +1,11 @@
 from pathlib import Path
 
-from sphinx_codelinks.bridge import convert_makred_content
+from sphinx_codelinks.needextend_bridge import convert_marked_content
 
 
-def test_bridge():
+def test_bridge(tmp_path):
     jsonpath = Path(__file__).parent / "data" / "analyse" / "marked_content.json"
-    convert_makred_content(jsonpath, outdir=Path(__file__).parent.parent / "output")
+    convert_marked_content(jsonpath, outdir=tmp_path)
+    needextend_path = tmp_path / "needextend.rst"
+
+    assert needextend_path.exists()