Add custom tutorials index page.

[JoeZiminski]

This PR introduces a potential new way to index sphinx-gallery generated pages rather than using the default sphinx-gallery pages. This follows from discussions such as #2327 #2800, where it was discussed that having more flexibility to integrate sphinx-generated tutorials and non-sphinx generated .rst files in the same index page would be useful. At present, what is a tutorials vs. how to is arbitrarily fixed by how the documentation is built.

The approach taken here is to

• Add a custom_tutorial_index.rst that replicates the current tutorials/index.rst page generated by sphinx (both are kept on the docs for now, for comparison).
• This required adding some custom .css to replicate some of the sphinx behaviour.

The documentation is available here.

Some benefits of this approach:

• Flexibility mix both sphinx-generated files and non-sphinx generated .rst files in the same index page.
• Easier to reorder the gallery cards, as well as select any desired thumbnail image.
• Can be extended to any index page for consistency across the documentation. For example, we might like such a presentation for the 'Getting Started' page or organise the How To's in the same way.
• Can add custom subtitles that are displayed on hover. I couldn't replicate exactly the sphinx mouse-hover behaviour, which shows the first line of the generated documentation file. In practice this leads to the preview obtained on hover to be kind of irrelevant / unhelpful. Here we can customise the text shown on hover to ensure it is informative.

Some drawbacks:

• This is more maintenance in the following ways:
  • We now have a custom .css file. This should never need to be changed, but nonetheless it is some added complexity in the docs codebase.
  • It is now necessary to manually add any new tutorials pages to the index, and the process is a little longer than normal (need to point to sphinx gallery file and image). This should however only need to be done once for any new pages. Instructions are at the top of the new index page.
• I couldn't perfectly replicate the sizing and mouse-hover behaviour of the sphinx gallery. Personally I prefer the bigger cards and targeted subtitles, but this is personal taste so this is a potential downside. I think nonetheless it I should be possible to further adjust the card size using css if desired.

EDITS:

• css / preview removed from final version
• developer documentation added.

[zm711]

Super busy day today so I'll give this a full read in the next couple days. I think this seems cool. I want to think about the concerns--adding css and html means that to contribute might become more daunting for the docs rather than a nice intro into the project so I'd like to think about looking good/dev preference vs inclusivity. But I'll do a full read soon :)

[JoeZiminski]

Thanks @zm711, looking forward to hearing your thoughts!

[zm711]

Any way to fix this?

[JoeZiminski]

Hey @zm711, it might be through the sphinx machinery but I am not sure. This is an issue with the current live docs as well i.e. here but does not appear for the proposed custom index. I guess another benefit of the flexibility is we can directly troubleshoot such issues rather than having to work around the sphinx-gallery rendering.

[JoeZiminski]

Hi everyone, I think this is done from my end. The CSS / hover feature is removed, and some additional docs added to the developer documentation. We can merge as normal merge (not squash) to keep the CSS stuff in the git history in case it is useful to return to later.

[zm711]

I just looked over the actual build and looks good to me. I think the adding new doc section looks good to. thanks from my side @JoeZiminski

[JoeZiminski]

@samuelgarcia @alejoe91 are you happy for this to be merged?

[zm711]

We can ping them again early next week. I think this is nice so let's get this merged :)