[DOC] move defaults in docs.py

[Remi-Gau]

Relates to #3519

Changes proposed in this pull request:

• move where defaults are located in the templates arguments in docs.py
• add info in contributing doc to show an example of a documented function:
• minor style fixing (semantic line break, markup variables in doc strings)

[github-actions]

👋 @Remi-Gau 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.

[Remi-Gau]

We can use this PR to start make sure we agree on where and how defaults should be reported and add an example in the contributing doc.

The changes here are supposed to reflect what was decided at the last maintainers meeting.

[codecov]

Codecov Report

Merging #3621 (3dc9a46) into main (ea375e0) will not change coverage.
The diff coverage is 100.00%.

@@           Coverage Diff           @@
##             main    #3621   +/-   ##
=======================================
  Coverage   91.54%   91.54%           
=======================================
  Files         133      133           
  Lines       15629    15629           
  Branches     3250     3250           
=======================================
  Hits        14307    14307           
  Misses        774      774           
  Partials      548      548           

Flag	Coverage Δ
macos-latest_3.10	91.46% <100.00%> (ø)
macos-latest_3.11	91.46% <100.00%> (ø)
macos-latest_3.8	91.42% <100.00%> (ø)
macos-latest_3.9	91.42% <100.00%> (ø)
ubuntu-latest_3.10	91.46% <100.00%> (ø)
ubuntu-latest_3.11	91.46% <100.00%> (ø)
ubuntu-latest_3.8	91.42% <100.00%> (ø)
ubuntu-latest_3.9	91.42% <100.00%> (ø)
windows-latest_3.10	91.40% <100.00%> (ø)
windows-latest_3.11	91.40% <100.00%> (ø)
windows-latest_3.8	91.37% <100.00%> (ø)
windows-latest_3.9	91.37% <100.00%> (ø)

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

Impacted Files	Coverage Δ
nilearn/_utils/docs.py	92.18% <100.00%> (ø)

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

[Remi-Gau]

the merge conflict is a headache: doing a hard reset on this one.

[ymzayek]

I started commenting the defaults that are not defined in docs.py but maybe a separate PR is needed to resolve these. There are 2 cases: defaults are not defined at all and defaults are set in the docstrings where the standard parameter is referenced

[bthirion]

LGTM otherwise

[bthirion]

LGTM otherwise.

[bthirion]

LGTM, thx.

[bthirion]

LGTM.