♻️ Improve validation and docs for needs_global_options

[chrisjsewell]

As discussed in #1409,
needs_global_options has overlapping functionality with needs_extra_options.
It makes more sense that needs_global_options is only used to define defaults for fields,
whereas needs_extra_options is for specifying new fields.

This PR restricts the keys allowed to:

• any needs_extra_options item
• any needs_extra_links item
• layout
• status
• style
• tags
• constraints

This means that projects with unknown keys will need to add them to needs_extra_options, e.g.

   needs_extra_options = ["option1"]
   needs_global_options = {
      'option1': 'Fix value'
   }

default values are also properly type checked and, for delimited string lists, converted to lists of strings.

[codecov]

Codecov Report

Attention: Patch coverage is 97.32143% with 3 lines in your changes missing coverage. Please review.

Project coverage is 88.54%. Comparing base (4e10030) to head (23c45cf).
Report is 134 commits behind head on master.

Files with missing lines	Patch %	Lines
sphinx_needs/needs.py	95.08%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1410      +/-   ##
==========================================
+ Coverage   86.87%   88.54%   +1.66%     
==========================================
  Files          56       60       +4     
  Lines        6532     7218     +686     
==========================================
+ Hits         5675     6391     +716     
+ Misses        857      827      -30     

Flag	Coverage Δ
pytests	88.54% <97.32%> (+1.66%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[danwos]

Thanks for the PR.

BTW: the way it works with the PR was how it was done releases ago.
You always needed both conf-options to add and modify the new extra_options.
But looks like this got somehow dropped/lost over time.

[chrisjsewell]

Thanks for the PR.

BTW: the way it works with the PR was how it was done releases ago.

You always needed both conf-options to add and modify the new extra_options.

But looks like this got somehow dropped/lost over time.

Ah good to know, so shouldn't break anything then 😅

[chrisjsewell]

@danwos is it me or do some of the docs examples make no sense:

needs_global_options = {'status': ('closed', 'status.lower() in ["done", "resolved", "closed"]')}

This could never take effect, because it is checking for an already set status, in which case a default would not be used

needs_global_options = {
      'status': [
            ('fulfilled', 'status.lower() in ["done", "resolved", "closed"]', 'type=="req"'),
            ('done', 'status.lower() in ["done", "resolved", "closed"]', 'type=="task"'),
            ('implemented', 'status.lower() in ["done", "resolved", "closed"]', 'type=="spec"')
      ]
   }

Same as above, but also:
The 3rd value of the tuple is meant to be the default, so why does it look like a filter?
Also, also, the logic here is weird, as it effectively does:

for (value, predicate, default) in list:
	if predicate(item):
		field = value
    else:
        field = default

so this means only the final default can ever take effect, the others get overridden

[santiagopagani]

@danwos Before this change, I was also using needs_global_options for defaulting the content field and enabling the hide tag for a special need type. This was working just fine, but now I'm getting warnings:

WARNING: needs_global_options 'content' must also exist in needs_extra_options, needs_extra_links, or ['constraints', 'layout', 'status', 'style', 'tags'] [needs.config]
WARNING: needs_global_options 'hide' must also exist in needs_extra_options, needs_extra_links, or ['constraints', 'layout', 'status', 'style', 'tags'] [needs.config]

However, content and hide are not extra options or extra links. They are intrinsic to need objects. Is there a simple way to get rid of this warning?

Thank you for your help.