From c2ad574d8a060af144d51ca2301fcfd2766cf48e Mon Sep 17 00:00:00 2001
From: Chris Sewell <chrisj_sewell@hotmail.com>
Date: Mon, 19 Feb 2024 09:36:07 +0000
Subject: [PATCH] =?UTF-8?q?=F0=9F=94=A7=20Type=20`ExternalSource`=20config?=
 =?UTF-8?q?=20dict=20(#1115)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 sphinx_needs/config.py         | 38 +++++++++++++++++++++++++++++++---
 sphinx_needs/external_needs.py |  1 +
 2 files changed, 36 insertions(+), 3 deletions(-)

diff --git a/sphinx_needs/config.py b/sphinx_needs/config.py
index 785436f7e..6a8808c87 100644
--- a/sphinx_needs/config.py
+++ b/sphinx_needs/config.py
@@ -69,6 +69,38 @@ class ConstraintFailedType(TypedDict):
     """If True, append styles to existing styles, else replace existing styles."""
 
 
+class ExternalSource(TypedDict, total=False):
+    """Defines an external source to import needs from.
+
+    External source will be a JSON with the key path::
+
+        versions -> <local project version> -> needs -> <list of needs>
+
+    """
+
+    # either
+    json_path: str
+    """A local path to a JSON file"""
+    # or
+    json_url: str
+    """A remote URL to a JSON object"""
+
+    version: str
+    """Override `current_version` from loaded JSON (optional)"""
+
+    base_url: str
+    """Used to create the `external_url` field for each need item (required)"""
+
+    target_url: str
+    """Used to create the `external_url` field for each need item (optional)"""
+
+    id_prefix: str
+    """Prefix all IDs from the external source with this string (optional, uppercased)"""
+
+    css_class: str
+    """Added as the `external_css` field for each need item (optional)"""
+
+
 @dataclass
 class NeedsSphinxConfig:
     """A wrapper around the Sphinx configuration,
@@ -300,10 +332,10 @@ def __setattr__(self, name: str, value: Any) -> None:
     debug_no_external_calls: bool = field(
         default=False, metadata={"rebuild": "html", "types": (bool,)}
     )
-    external_needs: list[dict[str, Any]] = field(
-        default_factory=list, metadata={"rebuild": "html", "types": ()}
+    external_needs: list[ExternalSource] = field(
+        default_factory=list, metadata={"rebuild": "html", "types": (list,)}
     )
-    """Reference external needs, outside of the documentation."""
+    """List of external sources to load needs from."""
     builder_filter: str = field(
         default="is_external==False", metadata={"rebuild": "html", "types": (str,)}
     )
diff --git a/sphinx_needs/external_needs.py b/sphinx_needs/external_needs.py
index 331038996..47d34a5d2 100644
--- a/sphinx_needs/external_needs.py
+++ b/sphinx_needs/external_needs.py
@@ -31,6 +31,7 @@ def get_target_template(target_url: str) -> Template:
 
 
 def load_external_needs(app: Sphinx, env: BuildEnvironment, _docname: str) -> None:
+    """Load needs from configured external sources."""
     needs_config = NeedsSphinxConfig(app.config)
     for source in needs_config.external_needs:
         if source["base_url"].endswith("/"):