✨ Add ndf role, deprecate need_func & [[...]] in need content

[chrisjsewell]

There are currently two ways to use dynamic functions within need directive's content:

1. [[copy("id")]]; is problematic, because it does not adhere to the rst/myst syntax specification, and has already show to cause issues and be surprising to users (🐛 FIX disallow dynamic functions [[..]] in literal content #1263)

2. :need_func:`[[copy("id")]]`; is better but overly verbose

In this PR, I introduce a new role, which I believe should supersede both: :ndf:`copy("id")` (open to other suggestions for the name)
Here we take the entire content to be the function, as so do not require the [[]], reducing verbosity and processing

Note, one thing that the role approach cannot do, is to allow placeholders in URLs, e.g. `link <http://www.[[copy('id')]]>`_
However, if this is truly required, then I believe we should introduce a new role specifically for that.

---

if this is accepted, I would then move to emit warnings if users already use [[...]], explaining how to replace them,
then eventually remove [[...]] after some deprecation period

---

things to clarify:

• do we agree this role should be added
• do we agree on its name
• do we agree this should deprecate [[...]] in content
  • do we need an additional role for URL links with placeholders
• do we agree this should deprecate need_func

[codecov]

Codecov Report

Attention: Patch coverage is 94.28571% with 2 lines in your changes missing coverage. Please review.

Project coverage is 87.00%. Comparing base (4e10030) to head (13fef98).
Report is 91 commits behind head on master.

Files with missing lines	Patch %	Lines
sphinx_needs/roles/need_func.py	90.90%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1269      +/-   ##
==========================================
+ Coverage   86.87%   87.00%   +0.12%     
==========================================
  Files          56       60       +4     
  Lines        6532     6970     +438     
==========================================
+ Hits         5675     6064     +389     
- Misses        857      906      +49     

Flag	Coverage Δ
pytests	87.00% <94.28%> (+0.12%)	⬆️

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.

[ubmarco]

Hi @chrisjsewell, thanks for this proposal.
As you said and as the past showed, the [[ ]] construct is brittle and breaks RST.
I like the role approach and also the name. Here are my answers:

• do we agree this role should be added
• do we agree on its name
• do we agree this should deprecate [[...]] in content
  • do we need an additional role for URL links with placeholders
• do we agree this should deprecate need_func

For the URL links I'm hesitant to add it without reported use case.
For ndf - can we somehow make sure that the name does not interfere with other extensions providing a role of the same name? need_func was certainly more scoped to SN.

[chrisjsewell]

Yeh cheers

can we somehow make sure that the name does not interfere

Eurgh, I would be very surprised if someone else was specifically using ndf 😅
Currently it will just override any existing role.
Happy to think of an even more specific name, but the idea was to make it not too verbose, similar to np

[ubmarco]

LGTM in general, docs and still deprecation missing, but can be done in an upcoming PR

[ubmarco]

if need_func is deprecated, please add a check for the warning in the test case

[danwos]

I'm okay with the changes. Good work.

But as this is a not backward-compatible change, we should add the docs and a depreciation warning for need_fuc with this PR.

[chrisjsewell]

But as this is a not backward-compatible change

yep I was already about to add docs and deprecations 👍 , but just to note, this PR on its own is backwards compatible; it is just adding a new role

[danwos]

Looks great. Thanks for the doc updates.

[ubmarco]

Nice work and good addition to SN.