Cleanup (#290)

* Prepare 1.5.0 release

* fix: plantuml dependency

* remove useless extra index url from python requirements

* refactor: split huge function

Author: AlexanderLanin

MODULE.bazel

@@ -13,7 +13,7 @@
 
 module(
     name = "score_docs_as_code",
-    version = "1.4.0",
+    version = "1.5.0",
     compatibility_level = 1,
 )
 

docs/conf.py

@@ -16,4 +16,8 @@
 project_prefix = "DOCS_"
 version = "0.1"
 
-extensions = ["score_sphinx_bundle"]
+extensions = [
+    # TODO remove plantuml here once docs-as-code is updated to sphinx-needs 6
+    "sphinxcontrib.plantuml",
+    "score_sphinx_bundle",
+]

src/extensions/score_metamodel/external_needs.py

@@ -137,64 +137,73 @@ def temp(self: NeedsList):
     NeedsList._finalise = temp  # pyright: ignore[reportPrivateUsage]
 
 
-def connect_external_needs(app: Sphinx, config: Config):
-    extend_needs_json_exporter(config, ["project_url", "project_prefix"])
-
-    bazel = app.config.external_needs_source or os.getenv("RUNFILES_DIR")
+def get_external_needs_source(external_needs_source: str) -> list[ExternalNeedsSource]:
+    bazel = external_needs_source or os.getenv("RUNFILES_DIR")
 
     if bazel:
-        external_needs = parse_external_needs_sources_from_DATA(
-            app.config.external_needs_source
-        )  # pyright: ignore[reportAny]
+        external_needs = parse_external_needs_sources_from_DATA(external_needs_source)
     else:
         external_needs = parse_external_needs_sources_from_bazel_query()  # pyright: ignore[reportAny]
 
-    for e in external_needs:
-        assert not e.path_to_target  # path_to_target is always empty
-        json_file = f"{e.bazel_module}+/{e.target}/_build/needs/needs.json"
-        if r := os.getenv("RUNFILES_DIR"):
-            logger.debug("Using runfiles to determine external needs JSON file.")
-            fixed_json_file = Path(r) / json_file
-        else:
-            logger.debug(
-                "Running outside bazel. "
-                "Determining git root for external needs JSON file."
-            )
-            git_root = Path.cwd().resolve()
-            while not (git_root / ".git").exists():
-                git_root = git_root.parent
-                if git_root == Path("/"):
-                    sys.exit("Could not find git root.")
-            logger.debug(f"Git root found: {git_root}")
-            fixed_json_file = (
-                git_root / "bazel-bin" / "ide_support.runfiles" / json_file
-            )
+    return external_needs
 
-        logger.debug(f"Fixed JSON file path: {json_file} -> {fixed_json_file}")
-        json_file = fixed_json_file
 
-        try:
-            needs_json_data = json.loads(Path(json_file).read_text(encoding="utf-8"))  # pyright: ignore[reportAny]
-        except FileNotFoundError:
-            logger.error(
-                f"Could not find external needs JSON file at {json_file}. "
-                + "Something went terribly wrong. "
-                + "Try running `bazel clean --async && rm -rf _build`."
-            )
-            continue
-
-        assert isinstance(app.config.needs_external_needs, list)  # pyright: ignore[reportUnknownMemberType]
-        app.config.needs_external_needs.append(  # pyright: ignore[reportUnknownMemberType]
-            {
-                "id_prefix": needs_json_data["project_prefix"],
-                "base_url": needs_json_data["project_url"]
-                + "/main",  # for now always "main"
-                "json_path": json_file,
-            }
+def add_external_needs_json(e: ExternalNeedsSource, config: Config):
+    json_file = f"{e.bazel_module}+/{e.target}/_build/needs/needs.json"
+    if r := os.getenv("RUNFILES_DIR"):
+        logger.debug("Using runfiles to determine external needs JSON file.")
+        fixed_json_file = Path(r) / json_file
+    else:
+        logger.debug(
+            "Running outside bazel. "
+            + "Determining git root for external needs JSON file."
         )
-        # Making the prefixes uppercase here to match sphinx_needs,
-        # as it does this internally too.
-        assert isinstance(app.config.allowed_external_prefixes, list)  # pyright: ignore[reportAny]
-        app.config.allowed_external_prefixes.append(  # pyright: ignore[reportUnknownMemberType]
-            needs_json_data["project_prefix"].upper()  # pyright: ignore[reportAny]
+        git_root = Path.cwd().resolve()
+        while not (git_root / ".git").exists():
+            git_root = git_root.parent
+            if git_root == Path("/"):
+                sys.exit("Could not find git root.")
+        logger.debug(f"Git root found: {git_root}")
+        fixed_json_file = git_root / "bazel-bin" / "ide_support.runfiles" / json_file
+
+    logger.debug(f"Fixed JSON file path: {json_file} -> {fixed_json_file}")
+    json_file = fixed_json_file
+
+    try:
+        needs_json_data = json.loads(Path(json_file).read_text(encoding="utf-8"))  # pyright: ignore[reportAny]
+    except FileNotFoundError:
+        logger.error(
+            f"Could not find external needs JSON file at {json_file}. "
+            + "Something went terribly wrong. "
+            + "Try running `bazel clean --async && rm -rf _build`."
         )
+        # Attempt to continue, exit code will be non-zero after a logged error anyway.
+        return
+
+    assert isinstance(config.needs_external_needs, list)  # pyright: ignore[reportUnknownMemberType]
+    config.needs_external_needs.append(  # pyright: ignore[reportUnknownMemberType]
+        {
+            "id_prefix": needs_json_data["project_prefix"],
+            "base_url": needs_json_data["project_url"]
+            + "/main",  # for now always "main"
+            "json_path": json_file,
+        }
+    )
+    # Making the prefixes uppercase here to match sphinx_needs,
+    # as it does this internally too.
+    assert isinstance(config.allowed_external_prefixes, list)  # pyright: ignore[reportAny]
+    config.allowed_external_prefixes.append(  # pyright: ignore[reportUnknownMemberType]
+        needs_json_data["project_prefix"].upper()  # pyright: ignore[reportAny]
+    )
+
+
+def connect_external_needs(app: Sphinx, config: Config):
+    extend_needs_json_exporter(config, ["project_url", "project_prefix"])
+
+    external_needs = get_external_needs_source(app.config.external_needs_source)
+
+    for e in external_needs:
+        assert not e.path_to_target  # path_to_target is always empty
+        assert e.target == "needs_json"
+
+        add_external_needs_json(e, app.config)

src/requirements.in

@@ -1,5 +1,3 @@
---extra-index-url https://pypi.org/simple/
-
 Sphinx
 
 # At least 4.2.0, as it fixes a bug in combination with esbonio live preview:

src/requirements.txt

@@ -4,8 +4,6 @@
 #
 #    bazel run //src:requirements.update
 #
---extra-index-url https://pypi.org/simple/
-
 accessible-pygments==0.0.5 \
     --hash=sha256:40918d3e6a2b619ad424cb91e556bd3bd8865443d9f22f1dcdf79e33c8046872 \
     --hash=sha256:88ae3211e68a1d0b011504b2ffc1691feafce124b845bd072ab6f9f66f34d4b7