👌 Remove hard-coding of completion and duration need fields (#1127)

These fields are used by `needgantt` but their name can be configured by `needs_duration_option` and `needs_completion_option`.
So in this commit, we remove the hard-coding and dynamically use these configuration options to set what option/key names are added.

sphinx_needs/config.py

@@ -257,9 +257,11 @@ def __setattr__(self, name: str, value: Any) -> None:
     duration_option: str = field(
         default="duration", metadata={"rebuild": "html", "types": (str,)}
     )
+    """Added to options on need directives, and key on need data items, for use by ``needgantt``"""
     completion_option: str = field(
         default="completion", metadata={"rebuild": "html", "types": (str,)}
     )
+    """Added to options on need directives, and key on need data items, for use by ``needgantt``"""
     needextend_strict: bool = field(
         default=True, metadata={"rebuild": "html", "types": (bool,)}
     )

sphinx_needs/data.py

@@ -175,35 +175,35 @@ class NeedsInfoType(TypedDict):
     parent_need: str
     """Simply the first parent id"""
 
-    # default extra options
-    # TODO these all default to "" which I don't think is good
-    duration: str
-    completion: str
-    # options from `BaseService.options` get added to every need,
-    # via `ServiceManager.register`, which adds them to `extra_options``
-    # GithubService
+    # Fields added dynamically by services:
+    # options from ``BaseService.options`` get added to ``NEEDS_CONFIG.extra_options``,
+    # via `ServiceManager.register`,
+    # which in turn means they are added to every need via ``add_need``
+    # ``GithubService.options``
     avatar: str
     closed_at: str
     created_at: str
     max_amount: str
     service: str
     specific: str
-    # _type: str  # type is already set in create_need
+    ## type: str  # although this is already an internal field
     updated_at: str
     user: str
-    # OpenNeedsService
+    # ``OpenNeedsService.options``
     params: str
     prefix: str
     url_postfix: str
-    # shared GithubService and OpenNeedsService
+    # shared ``GithubService.options`` and ``OpenNeedsService.options``
     max_content_lines: str
     id_prefix: str
     query: str
     url: str
 
-    # Note there are also:
-    # - dynamic default options that can be set by needs_extra_options config
-    # - dynamic global options that can be set by needs_global_options config
+    # Note there are also these dynamic keys:
+    # - items in ``needs_extra_options`` + ``needs_duration_option`` + ``needs_completion_option``,
+    #   which get added to ``NEEDS_CONFIG.extra_options``,
+    #   and in turn means they are added to every need via ``add_need`` (as strings)
+    # - keys in ``needs_global_options`` config are added to every need via ``add_need``
 
 
 class NeedsPartsInfoType(NeedsInfoType):

sphinx_needs/defaults.py

@@ -219,8 +219,6 @@
     "template": directives.unchanged_required,
     "pre_template": directives.unchanged_required,
     "post_template": directives.unchanged_required,
-    "duration": directives.unchanged_required,
-    "completion": directives.unchanged_required,
     "constraints": directives.unchanged_required,
     "constraints_passed": directives.unchanged_required,
     "constraints_results": directives.unchanged_required,

sphinx_needs/directives/need.py

@@ -128,11 +128,9 @@ def run(self) -> Sequence[nodes.Node]:
         template = self.options.get("template")
         pre_template = self.options.get("pre_template")
         post_template = self.options.get("post_template")
-        duration = self.options.get("duration")
-        completion = self.options.get("completion")
         constraints = self.options.get("constraints", [])
 
-        need_extra_options = {"duration": duration, "completion": completion}
+        need_extra_options = {}
         for extra_link in self.needs_config.extra_links:
             need_extra_options[extra_link["option"]] = self.options.get(
                 extra_link["option"], ""

sphinx_needs/needs.py

@@ -364,16 +364,20 @@ def load_config(app: Sphinx, *_args: Any) -> None:
             "Sphinx-Needs 0.7.2 is list. Please see docs for details."
         )
 
-    extra_options = NEEDS_CONFIG.extra_options
     for option in needs_config.extra_options:
-        if option in extra_options:
+        if option in NEEDS_CONFIG.extra_options:
             LOGGER.warning(
                 f'extra_option "{option}" already registered. [needs.config]',
                 type="needs",
                 subtype="config",
             )
         NEEDS_CONFIG.extra_options[option] = directives.unchanged
 
+    # ensure options for ``needgantt`` functionality are added to the extra options
+    for option in (needs_config.duration_option, needs_config.completion_option):
+        if option not in NEEDS_CONFIG.extra_options:
+            NEEDS_CONFIG.extra_options[option] = directives.unchanged_required
+
     # Get extra links and create a dictionary of needed options.
     extra_links_raw = needs_config.extra_links
     extra_links = {}
@@ -384,8 +388,8 @@ def load_config(app: Sphinx, *_args: Any) -> None:
     title_from_content = needs_config.title_from_content
 
     # Update NeedDirective to use customized options
-    NeedDirective.option_spec.update(extra_options)
-    NeedserviceDirective.option_spec.update(extra_options)
+    NeedDirective.option_spec.update(NEEDS_CONFIG.extra_options)
+    NeedserviceDirective.option_spec.update(NEEDS_CONFIG.extra_options)
 
     # Update NeedDirective to use customized links
     NeedDirective.option_spec.update(extra_links)
@@ -426,7 +430,7 @@ def load_config(app: Sphinx, *_args: Any) -> None:
             "-links_back": directives.flag,
         }
     )
-    for key, value in extra_options.items():
+    for key, value in NEEDS_CONFIG.extra_options.items():
         NeedextendDirective.option_spec.update(
             {
                 key: value,
@@ -512,15 +516,6 @@ def prepare_env(app: Sphinx, env: BuildEnvironment, _docname: str) -> None:
     for needs_func in needs_config.functions:
         register_func(needs_func)
 
-    # Own extra options
-    for option in [
-        "duration",
-        "completion",
-    ]:
-        # Check if not already set by user
-        if option not in NEEDS_CONFIG.extra_options:
-            NEEDS_CONFIG.extra_options[option] = directives.unchanged
-
     # The default link name. Must exist in all configurations. Therefore we set it here
     # for the user.
     common_links = []