DOC: Fix dwi module function cross ref in docstring

[jhlegarreta]

Fix dwi module function cross ref in docstring: provide the appropriate module where draw_points dwells.

Introduced inadvertently in commit 9f561d1 when the code was relocated from eddymotion.

Take advantage of the commit to improve the description of the method:

• Specify how the colors are assigned.
• Cross-reference the draw_points function using the Sphinx seealso tag.
• Use the tilde to shorten the link: display only the function name without the modules.

[jhlegarreta]

Looks like the documentation is not being built correctly:
https://nireports--103.org.readthedocs.build/en/103/api/nireports.interfaces.dmri.html

Was already happening before:
https://nireports.readthedocs.io/en/latest/api/nireports.interfaces.dmri.html

The readthedocs log shows multiple failures related to the interfaces and reportlets modules. Warnings are the same as the ones reported in nipreps/sdcflows#439

Should be addressed in a separate PR.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 58.43%. Comparing base (3c7f0bd) to head (977f26a).
Report is 4 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #103      +/-   ##
==========================================
+ Coverage   58.27%   58.43%   +0.16%     
==========================================
  Files          22       22              
  Lines        2085     2086       +1     
  Branches      321      364      +43     
==========================================
+ Hits         1215     1219       +4     
+ Misses        787      783       -4     
- Partials       83       84       +1     

Flag	Coverage Δ
unittests	58.27% <ø> (ø)

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.

[effigies]

I think the problem is that we import from the package in docs/conf.py without installing it. Thus, imports like numpy fail before sphinx has an opportunity to use autodoc_mock_imports.

[effigies]

Hmm, no it is installed. Possibly the autodoc mock is interfering?

[effigies]

Looks like that fixed it: https://nireports--103.org.readthedocs.build/en/103/api/nireports.interfaces.dmri.html (I had to refresh the cache to see it.)

[effigies]

I fixed a couple small errors that were preventing the admonitions from being shown. Let me know if you'd rather they be pulled into a different PR.

[jhlegarreta]

Fine with me. Thanks for the investigation on the documentation failures Chris.

Will merge as soon as soon as CIs become green.