New theme for documentation

[alexisthual]

This PR resolves #3122 and changes the documentation theme to furo for a better looking, more readable and accessible website!

You can preview these changes (without running the examples) by pulling this branch and running:

python -m pip install -r requirements-build-docs.txt
cd doc
make clean && make html-noplot
firefox _build/html/index.html

The main changes are:

• add a "Quickstart" page which mirrors ./README.md
• documentation sidebar and navigation
  • display examples' subsections in the sidebar ¹
    • open and merge PR allowing nested sections in sphinx-gallery
  • shorter names for doc sections and subsections (like "Contributing", "Introduction", "Maintenance", "API References", "Changelog", etc)
  • create individual page for each module (new files are in doc/modules)
  • redirect links from doc/modules/references.rst to new individual pages or just leave this file for now (I added a warning saying this part of the doc is no longer maintainted)
  • move most basic tutorials to a new examples/00_tutorials folder for more consistent site structure (this will break some existing urls)
  • redirect urls of previous tutorials to new tutorials
• better landing page
• better looking tabs for installation (resolves Replace installation HTML file with sphinx-tabs extension #3107)
• better looking binder buttons
• favicon with nilearn logo
• make the logo compatible with light and dark themes
• add new dependencies to requirements-build-docs.txt (furo, recommonmark, sphinx-design)
• remove custom components (from tune_toc.rst and big_toc_css.rst)
• enable markdown (we might want to get rid of this)
• customise default thumbnail for examples gallery

Before deploying these changes, we should:

• re-read the whole documentation (I'll list the sections and assign names of people willing to participate!)
• check that the examples build fine

Footnotes

1. furo generates two sidebars: the left one shows the website's structure, the right one shows current document's structure. The one to the left is a sphinx table of content generated with titles_only=True, which we can't change. This means that the left sidebar represents the exact site structure. If we want examples to be grouped in subsections in the sidebar, we need to create a new nested structure similar to what I did for doc/modules. However, examples are generated using sphinx-gallery, so we can either wait for a sphinx-gallery issue mentioning nested sections to be solved or generate an individual gallery for each subsection (I'll try the first option quickly and jump to the second if it's not obvious). ↩

[github-actions]

👋 @alexisthual 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"
• Code is PEP8-compliant.
• (Bug fixes) There is at least one test that would fail under the original bug conditions.
• (New features) There is at least one unit test per new function / class.
• (New features) The new feature is demoed in at least one relevant example.

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

[codecov]

Codecov Report

Merging #3125 (cee379a) into main (3edfea8) will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##             main    #3125   +/-   ##
=======================================
  Coverage   90.62%   90.62%           
=======================================
  Files         126      126           
  Lines       14898    14898           
  Branches     3060     3060           
=======================================
  Hits        13502    13502           
  Misses        825      825           
  Partials      571      571           

📣 Codecov can now indicate which changes are the most critical in Pull Requests. Learn more

[alexisthual]

To ease further discussions, here are some screenshots!

Regarding the landing page, I made the calls to action standout more and turned the carousel into a list of featured examples:

The examples' section hierarchy now works as intended. I still need to open and merge a PR for sphinx-gallery with these changes.

I replaced tabs from the installation section with tabs from sphinx-design:

[alexisthual]

We discussed having a live preview of these changes to proofread them before deploying.

I created a repo with the dev build of the docs so that we can see it using github pages.
It is accessible here: https://nilearn-doc-dev.github.io/index.html

However, it seems that css files from _static cannot be queried correctly (I don't know why 🤷 ) so it doesn't look good
EDIT: it works now (had to disable building with jekyll), we can start exploring it!

[GaelVaroquaux]

However, it seems that css files from _static cannot be queried correctly, I don't know why 🤷

Maybe it's a case of github's jekyll engine interfeering (in jekyll, I think that files starting with an underscore have a special meaning. You can add an empty file named ".nojekyll" in the root of the html repo to try to fix the problem: https://github.blog/2009-12-29-bypassing-jekyll-on-github-pages/

[tbng]

The new theme looks neat! It renders well on my mobile phone using firefox mobile as well.

I'm not sure about the content bar (column?) on the right side though. Maybe a better place is to also place it on the left -- although I guess this requires tuning a lot from the theme and not desireable.

Also for now the Featured examples links on the main page does not work (all links to the Quick Start page).

[alexisthual]

Sooo, I still need to make minor changes to the code, but I think we can start reading the documentation!

Current version is accessible here: https://nilearn-doc-dev.github.io

As discussed during the last nilearn dev meeting, I'll assign some parts of the documentation to read, but feel free to change these assignments! (and to tag people who might be interested)

Examples

• Basic tutorials @alexisthual
• Visualization of brain images @alexisthual
• Decoding @htwangtw
• Functional connectivity @htwangtw
• GLM first level @tsalo
• GLM second level @tsalo
• Manipulating brain volumes @emdupre
• Advanced statistical analysis @emdupre

Other

• Main page @jeromedockes
• Quickstart @jeromedockes
• User guide @jeromedockes (there might be a lot to say about this one)
• API references @NicolasGensollen from connectivity to interfaces included, @bthirion the rest
• Glossary @NicolasGensollen , related to Links direct to the old version of documentation #3163
• All sections from the Development part in the sidebar (Migration, Contributing, etc) @tbng if you want 🙂

Our main goals are:

1. check that generated pages look ok (on laptop and mobile resolutions ; in most browsers, you can right click + "Inspect" to change viewport resolution)
2. quickly check that links seem correct
3. check for parts with custom css, js, etc which would need some refactoring (like tabs or carrousels for instance)
4. try to unify style. I encountered many different styles of notes, warnings, etc. I suggest we stick to admonition items from furo

[tsalo]

Everything in the first- and second-level GLM examples looks good to me. I saw the table of contents issue, but it looks like you're already aware of that. I do feel like the examples sections of the reference pages have a lot of wasted space by having the examples listed vertically.

[alexisthual]

Everything in the first- and second-level GLM examples looks good to me. I saw the table of contents issue, but it looks like you're already aware of that. I do feel like the examples sections of the reference pages have a lot of wasted space by having the examples listed vertically.

Sorry, currently, what issue do you see with the table of content? (it's supposed to be solved haha)
Also, what do you call the "reference pages"? Could you please send screenshots of the wasted space you mention? 🙂

Besides, I just found a broken link by chance in https://nilearn-doc-dev.github.io/auto_examples/04_glm_first_level/plot_fixed_effects.html#glm-estimation (link to the nistat's documentation), could you do a quick pass to check there aren't any of these? Thank you!

[tsalo]

Sorry, currently, what issue do you see with the table of content?

This is what I'm seeing:

It's still present in https://nilearn-doc-dev.github.io/auto_examples/04_glm_first_level/plot_bids_features.html#sphx-glr-auto-examples-04-glm-first-level-plot-bids-features-py and https://nilearn-doc-dev.github.io/auto_examples/04_glm_first_level/plot_first_level_details.html#sphx-glr-auto-examples-04-glm-first-level-plot-first-level-details-py, at least.

Also, what do you call the "reference pages"? Could you please send screenshots of the wasted space you mention?

I'm referring to the API documentation. For example, on the page for FirstLevelModel, the examples look like this:

In the official documentation, they look like this:

It's not a big deal, but there ends up being a lot of empty space with that organization, and some functions or classes that show up in a lot of examples are going to have very long example sections.

Besides, I just found a broken link by chance in https://nilearn-doc-dev.github.io/auto_examples/04_glm_first_level/plot_fixed_effects.html#glm-estimation (link to the nistat's documentation), could you do a quick pass to check there aren't any of these?

I did notice that, but it's also present in the official documentation, so it's a typo in the actual RST page rather than a problem with the new theme.

[alexisthual]

Thanks a lot, that's exactly the kind of feedback I need :)

[alexisthual]

Soooo, a new version of sphinx-gallery with the changes we need just came out 🎉 sphinx-gallery/sphinx-gallery#981
The CI now runs without error, so I would advocate to merge this soon. Indeed, some parts of the documentation might benefit from a more careful read, but I think we proofread a great part of the website already and feel confident it won't crash. Moreover, I am deploying an updated preview of the docs here for ultimate tests: https://nilearn-doc-dev.github.io/

However, while we're here, we might as well plan some changes for the documentation.

1. In my humble opinion, we could do a much better job with the User Guide. In particular:
2. It is filled with interesting examples, references and pieces of code, but sometimes feels like a patchwork. I think it would greatly benefit from being harmonized by someone who could spend the time to read it entirely. Maybe we could make that a nilearn dev days project for new-comers?
3. Moreover, I'd be in favor of giving it a more precise and catchy name: To me, it almost feels like a short textbook on fMRI, why not name it this way?
4. Its main page looks a bit rough haha, but we can change that later.
5. Oftentimes, examples are ordered in a suboptimal way within sections. I think this is an important aspect of how we introduce core features of the library to users, and ultimately we should find a way to polish a more straight-to-the-point interface.

[bthirion]

Thx ! Since your suggestions are big steps, shouldn't we proceed by first merging that one and then reviewing more in detail the documentation ?

[ymzayek]

I agree with those points @alexisthual. I am also in favor of merging this first and then working through them. I trust it has been reviewed sufficiently but I can have a look today at the updated docs just to check it overall.

[ymzayek]

Hi @alexisthual, there are a few small things I think we can try to fix before merging.

• The note on this page is in italics and centered. Reformat to look like the others.
• There is an error on this page
• Plots are rendered very small here and also some plots here
• Isn't this module supposed to be called maskers instead of masking

Also ok if you think some things are better fixed separately in a different PR after merging this. Let me know.

[ymzayek]

Isn't this module supposed to be called maskers instead of masking

Actually this is reflecting the current documentation and can stay as is.

But this related comment should be addressed: #3125 (comment)

[alexisthual]

Thanks for your comments @ymzayek, I addressed all of them in my last commit.

Point by point:

• I had to modify ./nilearn/reporting/data/html/report_body_template_niftilabelsmasker.html ; more generally, this folder is filled with HTML / CSS content I don't really like haha
• removing the table of content removed the error
• fixed this with a minor addition to our custom CSS file to handle image lists generated by sphinx-gallery
• good catch, a section was actually missing in the API references (I had split reference.rst for more readability, and missed that input_data was renamed to maskers)

[jeromedockes]

5. Oftentimes, examples are ordered in a suboptimal way within sections. I think this is an important aspect of how we introduce core features of the library to users, and ultimately we should find a way to polish a more straight-to-the-point interface.

see also #3195

[ymzayek]

Thanks @alexisthual for the quick changes! For me I think it is in a good state to merge.

[ymzayek]

@alexisthual can you also add an entry to doc/changes/latest.rst?

[bthirion]

I haven't identified any big issue in the rendering. Thx a lot !

[bthirion]

Many thx for modernizing the doc !

[ymzayek]

When everything passes 🤞 I will have a quick look at the artifacts and then merge.

[ymzayek]

@alexisthual I really think it's almost there! The fix in AUTHORS.rst should do the trick. See below.

[ymzayek]

Thanks @alexisthual and all reviewers for your work on this. Merging!