Consider using the Sphinx Basic NG theme as a parent of this theme

[choldgraf]

Currently we are depending on the basic Sphinx parent theme and using Bootstrap to define the scaffolding of this theme. This was a quick way to get started without extensive CSS/HTML knowledge, but we should decide if this is the best theme's structure moving forward.

Recently, @pradyunsg has been working on a "modern" version of the basic Sphinx template, that uses some best-practices and more modern CSS tools (like flexbox) to accomplish more with less code.

We should discuss whether it is worth refactoring this theme to depend on the sphinx-basic-ng theme. Some questions to consider would be:

• Does this come with any out-of-the-box improvements to our HTML structure?
• Would this make the theme easier to debug and maintain?
• Would it reduce the complexity of our codebase significantly?
• Would any benefits above be worth the effort to refactor?

Tasks to complete

• [ ] Discuss the questions above and decide if we want to move forward with this
• [ ] Understand from @pradyunsg if the basic-ng theme is in a place to be depended on yet (it still has WIP in the readme!)
• [ ] Decide on next steps...

[drammock]

I like this idea in principle, but in practice it might be non-trivial for theme users to adapt to this change. For example, in MNE-Python's theme customizations we make use of bootstrap classes (mostly on our homepage); at a minimum it sounds like we'd have to re-work those. For us I don't think it would be too bad, but other sites may have done more customization of templates than we have and thus have more work to do.

[jorisvandenbossche]

@drammock that's a good point. I think as part of exploring this, it might be useful to list the main open source projects that adapt the theme, check which aspects and how they modify it, and evaluate if this would be relatively straightforward to migrate.

Part of the solution (I think) will also be to provide some of such customizations as part of the theme (as built-in options, or as clear examples how to do in the documentation). Part of the widgets you are using might also be covered by sphinx-design (https://sphinx-design.readthedocs.io/, the new version of https://github.com/executablebooks/sphinx-panels). (didn't check in detail, to be clear, for example not directly sure how that would work with jinja templating to fill in content as you are doing now).

We could also check to what extent you can still use those classes within the content of the main page as end user of the theme by including bootstrap css yourself (I don't know to what extent that works if the outer divs are not using bootstrap classes).

[pradyunsg]

• Understand from @pradyunsg if the basic-ng theme is in a place to be depended on yet (it still has WIP in the readme!)

That's mostly because (1) I wanna document all the things and (2) I don't wanna remove WIP until we know it's actually proven to be usable in a real theme.

If whatever's there right now doesn't work, the process of trying to port this theme would help inform how that has to change -- tell me if there's something that's not possible or frustratingly difficult. I'm happy to try and accomodate for the needs of this theme (and book, and Furo, and whomever else is interested)!