[DOC] render reports in the documentation

[Remi-Gau]

• Closes Adding tests for rapid inspection of visual elements #2194
• Closes improve documentation of nilearn/reporting/_visual_testing/_glm_reporter_visual_inspection_suite_.py #3665

Changes proposed in this pull request:

• generated GLM reports examples during doc build
• add the html document to the doc
• add reports for maskers (in another PR)

[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.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 92.09%. Comparing base (abb80ff) to head (b5c905c).
Report is 15 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4267      +/-   ##
==========================================
+ Coverage   91.85%   92.09%   +0.24%     
==========================================
  Files         144      143       -1     
  Lines       16419    16412       -7     
  Branches     3434     3438       +4     
==========================================
+ Hits        15082    15115      +33     
+ Misses        792      758      -34     
+ Partials      545      539       -6     

Flag	Coverage Δ
macos-latest_3.10_test_plotting	91.96% <ø> (?)
macos-latest_3.11_test_plotting	91.96% <ø> (+0.11%)	⬆️
macos-latest_3.12_test_plotting	91.96% <ø> (?)
macos-latest_3.8_test_plotting	91.92% <ø> (?)
macos-latest_3.9_test_plotting	91.93% <ø> (?)
ubuntu-latest_3.10_test_plotting	91.96% <ø> (+0.11%)	⬆️
ubuntu-latest_3.11_test_plotting	91.96% <ø> (?)
ubuntu-latest_3.12_test_plotting	91.96% <ø> (?)
ubuntu-latest_3.12_test_pre	91.96% <ø> (?)
ubuntu-latest_3.8_test_plot_min	91.67% <ø> (?)
ubuntu-latest_3.8_test_plotting	91.92% <ø> (?)
ubuntu-latest_3.9_test_plotting	91.93% <ø> (?)
windows-latest_3.10_test_plotting	91.94% <ø> (?)
windows-latest_3.11_test_plotting	91.94% <ø> (?)
windows-latest_3.12_test_plotting	91.94% <ø> (?)
windows-latest_3.8_test_plotting	91.90% <ø> (?)
windows-latest_3.9_test_plotting	91.91% <ø> (?)

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.

[Remi-Gau]

GLM examples would be listed in the reporting part of the API section:

https://output.circle-artifacts.com/output/job/2b5386ab-b387-4f7c-a15f-1ba11700e3b8/artifacts/0/dev/modules/reporting.html

The GLM reports example page would look like this:

https://output.circle-artifacts.com/output/job/2b5386ab-b387-4f7c-a15f-1ba11700e3b8/artifacts/0/dev/modules/generated_glm_reports/reports_examples.html

[Remi-Gau]

If we generate the GLM reports on every doc build it would add 4 minutes to the doc build time: https://github.com/nilearn/nilearn/actions/runs/7888150339/job/21524981188?pr=4267#step:34:1588

Probably only worth doing on main or when requesting a [full doc] build.

[Remi-Gau]

• blocked by [BUG] NiftiSpheresMasker reports do not show sphere where there is only one #4268

[bthirion]

Where can we see the result of this build ?

[Remi-Gau]

Should be viewable if we ask for a full build of the doc in the PR otherwise it will be build only after a full build in main?

https://nilearn.github.io/stable/development.html#building-documentation

git commit --allow-empty -m "[full doc] request full build"

Will trigger a full build on this PR.

Do you think that this should be treated like the examples, that is we trigger a build of only the examples that have been touched by a PR?

[Remi-Gau]

@bthirion

to view the GLM reports as part of the doc

https://output.circle-artifacts.com/output/job/b7e150cb-ce03-42b8-b6f3-a1105c7a66d4/artifacts/0/dev/modules/generated_reports/glm_reports_examples.html

[bthirion]

Do you think that this should be treated like the examples, that is we trigger a build of only the examples that have been touched by a PR?

Makes sense to me.