[MAINT] add warning to deprecate darkness

[alishakodibagkar]

Closes #3501

Changes proposed in this pull request:

• Edited plotting/surf_plotting.py to add a deprecation warning for darkness
• Edited plotting/tests/test_surf_plotting.py to test warning

@Remi-Gau

[github-actions]

👋 @alishakodibagkar Thanks for creating a PR!

Until this PR is ready for review, you can include the [WIP] tag in its title, or leave it as a github draft.

Please make sure it is compliant with our contributing guidelines. In particular, be sure it checks the boxes listed below.

• PR has an interpretable title.
• PR links to Github issue with mention Closes #XXXX (see our documentation on PR structure)
• Code is PEP8-compliant (see our documentation on coding style)
• Changelog or what's new entry in doc/changes/latest.rst (see our documentation on PR structure)

For new features:

• There is at least one unit test per new function / class (see our documentation on testing)
• The new feature is demoed in at least one relevant example.

For bug fixes:

• There is at least one test that would fail under the original bug conditions.

We will review it as quick as possible, feel free to ping us with questions if needed.

[codecov]

Codecov Report

Merging #3855 (4bb2da4) into main (e002d24) will increase coverage by 0.00%.
The diff coverage is 100.00%.

❗ Current head 4bb2da4 differs from pull request most recent head f5e468f. Consider uploading reports for the commit f5e468f to get more accurate results

@@           Coverage Diff           @@
##             main    #3855   +/-   ##
=======================================
  Coverage   91.59%   91.59%           
=======================================
  Files         134      134           
  Lines       15694    15698    +4     
  Branches     3270     3270           
=======================================
+ Hits        14375    14379    +4     
  Misses        770      770           
  Partials      549      549           

Flag	Coverage Δ
macos-latest_3.10	91.52% <100.00%> (+<0.01%)	⬆️
macos-latest_3.11	91.52% <100.00%> (+<0.01%)	⬆️
macos-latest_3.8	91.48% <100.00%> (+<0.01%)	⬆️
macos-latest_3.9	91.48% <100.00%> (+<0.01%)	⬆️
ubuntu-latest_3.10	91.52% <100.00%> (+<0.01%)	⬆️
ubuntu-latest_3.11	?
ubuntu-latest_3.8	?
ubuntu-latest_3.9	?
windows-latest_3.10	91.46% <100.00%> (+<0.01%)	⬆️
windows-latest_3.11	91.46% <100.00%> (+<0.01%)	⬆️
windows-latest_3.8	91.42% <100.00%> (+<0.01%)	⬆️
windows-latest_3.9	91.42% <100.00%> (+<0.01%)	⬆️

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

Impacted Files	Coverage Δ
nilearn/plotting/html_surface.py	100.00% <100.00%> (ø)
nilearn/plotting/surf_plotting.py	95.89% <100.00%> (+0.02%)	⬆️

📣 We’re building smart automated test selection to slash your CI/CD build times. Learn more

[Remi-Gau]

Love the title of this PR: I wished I too could deprecate darkness from life. :-p

[Remi-Gau]

There seems to be some import sorting issue.

https://github.com/nilearn/nilearn/actions/runs/5604371031/jobs/10252858142?pr=3855#step:5:12

Try running:

isort .

in the root nilearn folder to fix the issue

[Remi-Gau]

Changes look good to me but you should:

• add an entry to the changelog
• add yourself to the list of contributors

see here: https://nilearn.github.io/dev/development.html#changelog

and ask us if you need guidance

[Remi-Gau]

@alishakodibagkar

See this comment from @alexisthual that mentions that we can deprecate more darkness:

#3501 (comment)

[ymzayek]

The other location being here:

nilearn/nilearn/plotting/html_surface.py

Lines 81 to 82 in e002d24

	if darkness is not None:
	bg_data *= darkness

[ymzayek]

I made some suggestions for changes. You can just commit them and then we can see if the CI passes, this should be ready to merge.

[ymzayek]

Thx @alishakodibagkar !

[Remi-Gau]

Good with me. Thanks a bunch @alishakodibagkar