🐛👌 Centralise need missing link reporting

[chrisjsewell]

Currently, warnings for need outgoing links that reference a non-existent ID, are only generated "indirectly" in the render phase; where NeedOutgoing nodes are converted to nodes that are understood by sphinx builders (HTML, PDF, ...).

Since this render phase is no longer needed/run for simply creating the needs.json, using the needs builder, these warnings are not generated.

Additionally, any needs that are not explicitly rendered in the documentation, like externally imported needs, are also skipped.

The reporting of unknown links is now moved to the check_links function, meaning it is now run for all needs and all builders. The warnings have also been given a subtype link_outgoing or external_link_outgoing, e.g.

srcdir/index.rst:12: WARNING: Need 'SP_TOO_002' has unknown outgoing link 'NOT_WORKING_LINK' in field 'links' [needs.link_outgoing]
WARNING: http://my_company.com/docs/v1/index.html#TEST_01: Need 'EXT_TEST_01' has unknown outgoing link 'SPEC_1' in field 'links' [needs.external_link_outgoing]

This means they can be suppressed using the standard Sphinx config:

suppress_warnings = ["needs.link_outgoing", "needs.external_link_outgoing"]` 

This deprecates the need for the needs_report_dead_links configuration, which now emits a deprecation warning if set by the user.

@danwos, do you agree that needs_report_dead_links can be deprecated, and that warnings should be emitted for unknown ids in external need links?

closes #1038
closes #1095

[codecov]

Codecov Report

Attention: 3 lines in your changes are missing coverage. Please review.

Comparison is base (f083bbd) 83.84% compared to head (ffc7be0) 83.83%.

Files	Patch %	Lines
sphinx_needs/needs.py	86.66%	2 Missing ⚠️
sphinx_needs/directives/need.py	90.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1104      +/-   ##
==========================================
- Coverage   83.84%   83.83%   -0.01%     
==========================================
  Files          56       56              
  Lines        6424     6421       -3     
==========================================
- Hits         5386     5383       -3     
  Misses       1038     1038              

Flag	Coverage Δ
pytests	83.83% <89.28%> (-0.01%)	⬇️

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.

[danwos]

Thanks for the fix. Looks good 👍 And I also agree needs_report_dead_links is deprecated with this change-

[arwedus]

Hi @danwos and @chrisjsewell , I've noticed in a local test that this does not raise warnings in case I've changed a need ID but forgot to update the links to it in other needs, when I'm building with the needs builder (or inventories builder).

/edit: Nevermind, it pulled in sphinx-needs 2.0.0 instead of master. Works now. Any chance of a new minor release soon?

[chrisjsewell]

Nevermind, it pulled in sphinx-needs 2.0.0 instead of master. Works now. Any chance of a new minor release soon?

Ah good 😄

yes I hope soon, I'd just like to push to try and finalise some of my outstanding PRs first 😅
probably another major, since some of the changes are "technically" a little breaking, but if you are already trying out master, then thats a good sign

[arwedus]

Nevermind, it pulled in sphinx-needs 2.0.0 instead of master. Works now. Any chance of a new minor release soon?

Ah good 😄

yes I hope soon, I'd just like to push to try and finalise some of my outstanding PRs first 😅 probably another major, since some of the changes are "technically" a little breaking, but if you are already trying out master, then thats a good sign

@chrisjsewell and @danwos: Looking forward to it. Even if it's a new major, please don't drop support for Python 3.8 yet, if any way possible.