You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This issue arises from when I was looking into the code considering #1082 and #1119
(@danwos as we discussed this morning)
The use of the config variable needs_extra_options and of the global variable NEEDS_CONFIG.extra_options seem inconsistent, in that:
Sometimes needs_extra_options is used, where it seems that NEEDS_CONFIG.extra_options should probably be used instead
NEEDS_CONFIG.extra_options is difficult to track, because at different stages it has new items added, which are obviously not taken into account in previous stages.
Below is a summary of their use in the code base:
Extra options are created by either:
A user adds them via the needs_extra_options configuration, as a list[str]
A user / extension uses api.configuration.add_extra_option to "programmatically" add a name to NEEDS_CONFIG.extra_options (raises NeedsApiConfigWarning if already added). For example sphinx-test-reports uses this in a config-inited event
They are used in the following places (in this order):
In load_config (config-inited event)
needs_extra_options are added to NEEDS_CONFIG.extra_options object (a warning is raised if one already exists)
each NEEDS_CONFIG.extra_options is added as an option on:
NeedDirective
NeedserviceDirective
NeedextendDirective (and also as +<name> -> unchanged and -<name> -> flag)
In check_configuration (config-inited event):
needs_filter_data keys are checked against needs_extra_options names; matching keys cause a NeedsConfigException
needs_extra_options names are checked against INTERNALS list; matching keys cause a NeedsConfigException
link type names (and their corresponding <name>_back key) are checked against needs_extra_options names; matching keys cause a NeedsConfigException
ensure all needs_variant_options keys match a needs_extra_options name, or a link type, or a default option; if not, a NeedsConfigException is raised
In prepare_env (env-before-read-docs event):
the ServiceManager is initialised and the GithubService and OpenNeedsService classes are registered via ServiceManager.register. In ServiceManager.register, for all options on the service class, the option is added to NEEDS_CONFIG.extra_options (if not already present)
In load_external_needs (env-before-read-docs event) for each loaded need, all fields in needs_extra_options are always kept (this data is then parsed on to add_external_need -> add_need)
In NeedDirective.run (called during read) for all names in NEEDS_CONFIG.extra_options gather pass kwargs to add_need, i.e. kwarks[name] = self.options.get(name, "")
It is of note that duration and completion are specifically gathered, but then surely must be overridden, since these are both added as defaults above (in prepare_env)
In NeedimportDirective.run, NEEDS_CONFIG.extra_options are added to the known_options list then, for each import need item, if a field is not in known_options it is dropped, the rest are passed to add_need
This is similar to the logic in load_external_needs, BUT that uses needs_extra_options instead of NEEDS_CONFIG.extra_options
In add_need (called before/during read) NEEDS_CONFIG.extra_options is passed to _merge_extra_options, as well as the kwargs passed to add_need:
All kwargs passed to add_need must either be in NEEDS_CONFIG.extra_options or in needs_extra_links (or a NeedsInvalidOption is raised)
In _merge_extra_options, for all the NEEDS_CONFIG.extra_options keys:
if the key is in kwargs, but not already set by add_need (i.e. is not an internal key), its value is set to kwargs[key], or
if the key is not already set by add_need (i.e. is not an internal key), it is set to a default value of ""
In NeedReportDirective, if required, need_extra_options are listed
The text was updated successfully, but these errors were encountered:
One thing else I note @danwos:
I see now that the duration and completion fields are added for use by the needgantt directive.
For this there are also needs_duration_option and needs_completion_option configuration options, to change the name of these fiels.
However, since duration and completion are hard-coded in the code base in a number of places,
I think if users were to use these configurations options to change the names, this would not work very well
This issue arises from when I was looking into the code considering #1082 and #1119
(@danwos as we discussed this morning)
The use of the config variable
needs_extra_options
and of the global variableNEEDS_CONFIG.extra_options
seem inconsistent, in that:needs_extra_options
is used, where it seems thatNEEDS_CONFIG.extra_options
should probably be used insteadNEEDS_CONFIG.extra_options
is difficult to track, because at different stages it has new items added, which are obviously not taken into account in previous stages.Below is a summary of their use in the code base:
Extra options are created by either:
needs_extra_options
configuration, as alist[str]
api.configuration.add_extra_option
to "programmatically" add aname
toNEEDS_CONFIG.extra_options
(raisesNeedsApiConfigWarning
if already added). For examplesphinx-test-reports
uses this in aconfig-inited
eventThey are used in the following places (in this order):
In
load_config
(config-inited
event)needs_extra_options
are added toNEEDS_CONFIG.extra_options
object (a warning is raised if one already exists)needs_duration_option
(defaultduration
) +needs_completion_option
(defaultcompletion
) are also added if not present (as of 👌 Remove hard-coding ofcompletion
andduration
need fields #1127)NEEDS_CONFIG.extra_options
is added as an option on:NeedDirective
NeedserviceDirective
NeedextendDirective
(and also as+<name> -> unchanged
and-<name> -> flag
)In
check_configuration
(config-inited
event):needs_filter_data
keys are checked againstneeds_extra_options
names; matching keys cause aNeedsConfigException
needs_extra_options
names are checked againstINTERNALS
list; matching keys cause aNeedsConfigException
<name>_back
key) are checked againstneeds_extra_options
names; matching keys cause aNeedsConfigException
needs_variant_options
keys match aneeds_extra_options
name, or a link type, or a default option; if not, aNeedsConfigException
is raisedIn
prepare_env
(env-before-read-docs
event):the
ServiceManager
is initialised and theGithubService
andOpenNeedsService
classes are registered viaServiceManager.register
. InServiceManager.register
, for alloptions
on the service class, the option is added toNEEDS_CONFIG.extra_options
(if not already present)additional "default" extra names are added to
NEEDS_CONFIG.extra_options
:(removed in 🔧 Removehidden
hidden
field fromextra_options
#1124),(removed 👌 Remove hard-coding ofduration
,completion
completion
andduration
need fields #1127),(removed in 🔧 Removeconstraints
constraints
fromextra_options
#1123) (if not already present)In
load_external_needs
(env-before-read-docs
event) for each loaded need, all fields inneeds_extra_options
are always kept (this data is then parsed on toadd_external_need -> add_need
)In
NeedDirective.run
(called during read) for all names inNEEDS_CONFIG.extra_options
gather passkwargs
toadd_need
, i.e.kwarks[name] = self.options.get(name, "")
duration
andcompletion
are specifically gathered, but then surely must be overridden, since these are both added as defaults above (inprepare_env
)In
NeedimportDirective.run
,NEEDS_CONFIG.extra_options
are added to theknown_options
list then, for each import need item, if a field is not inknown_options
it is dropped, the rest are passed toadd_need
load_external_needs
, BUT that usesneeds_extra_options
instead ofNEEDS_CONFIG.extra_options
In
add_need
(called before/during read)NEEDS_CONFIG.extra_options
is passed to_merge_extra_options
, as well as thekwargs
passed toadd_need
:All
kwargs
passed toadd_need
must either be inNEEDS_CONFIG.extra_options
or inneeds_extra_links
(or aNeedsInvalidOption
is raised)In
_merge_extra_options
, for all theNEEDS_CONFIG.extra_options
keys:kwargs
, but not already set byadd_need
(i.e. is not an internal key), its value is set tokwargs[key]
, oradd_need
(i.e. is not an internal key), it is set to a default value of""
In
NeedReportDirective
, if required,need_extra_options
are listedThe text was updated successfully, but these errors were encountered: