New theme based on Bootstrap 4: contributing (parts) upstream?

[jorisvandenbossche]

We have been working on a Bootstrap-based sphinx theme recently: https://github.com/pandas-dev/pandas-sphinx-theme

We originally wanted to start from this theme, but in the end started from "scratch" (while still looking at the source code here) because we wanted to use bootstrap 4, add some additional features and also ended up with a different layout.
However, I think it would still be interesting to see if this project would welcome some changes to be contributed to this repo.

Some general remarks about this theme:

• We are using Bootstrap 4, while this repo right now is using Bootstrap 2 / 3 (with compatibility for both in the layouts). But from the discussion in Support for bootstrap 4? #146, I understood you would be fine with moving to Bootstrap 4 exclusively (so not keeping compatibility with older bootstrap versions), if doing a proper version bump to indicate this.
• We are using a "BootstrapHTML5Translator", inspired on open PRs in this repo: Customized and bootstrap-ifyed HTMLTranslator #92, Additional custom html writer changes #104. This would replace some javascript code.
• We are also using "navigation objects" in the jinja2 templates to control the formatting of the navigation items, instead of letting sphinx generate the hard-coded html (eg the {{ toctree(maxdepth=...) }} in the layout here) and then have javascript to "fix up" the html generated by sphinx.
  See https://github.com/pandas-dev/pandas-sphinx-theme/blob/81683c21877fb21d443be5e7a5f7ba50713950ad/pandas_sphinx_theme/docs-toc.html#L3-L16 for an example how the styled html for the navigation is created in the template.
  Currently, this relies on a monkeypatch of sphinx (not ideal, but it's a quite robust one I think, see https://github.com/pandas-dev/pandas-sphinx-theme/blob/master/pandas_sphinx_theme/__init__.py). Ideally this would be included in sphinx itself, but for now this "hack" is working fine for us. Having full control on the layout (instead of having javascript correct it "on the fly") is a big plus IMO.

• We have a different default layout as the layouts included in this repo (there is a navbar, and two sidebars). This will certainly not be a suitable layout for all documentation (it was originally developed for a doc site with a lot of pages).
  I think it would be interesting to see if it is easy to refactor the layout in this repo with the infrastructure (as explained above) of our new theme.

So I might be "cutting right to the chase" here without much prior context, but some questions:

• Would there be interest in those elements described above?
• Would there be interest in the layout described above? A possible question here is to what extent it is possible for a single package to distribute different sets of layouts (there is no one layout that rules them all ;))

Personally, I would be happy to see efforts combined. But, it might well be that the more complex layout and some other elements (version dropdowns, ..) in our new theme are "out of scope" for this theme, or that the approach is too different to combine, .. Even then, it might still make sense to see if certain common parts could be shared if there is interest. And at least I wanted to make you aware of the efforts going on in the other package.

[ryan-roemer]

I'd definitely be up for changes to get the theme up to BS4.

At the same time, I'm spending very little time in Python these days, and recently found out my now antiquated fab-based PyPI publishing scripts are broken and will need a catch up to modern Python libs + PyPI. So, ideally, I'd be looking for some help with the overall infrastructure and release pipeline too.

(Helpfully, I do a ton of JS in my day job, so if there are any lingering issues JS-side with BS4 integration, I'll be definitely able to jump in and get things going.)

If you're potentially up for needing to help me along that extra bit, I'd love to see this theme get lifted up and modernized. Ideally in small and digestible PRs, but I'd take big ones as well as long as I'm able to get up a dev environment going and kick the tires on the theme.

Thanks so much for reaching out and appreciate the great work you've already done in your other theme project!

[svenevs]

Yay! Thanks @jorisvandenbossche !!!

I can update the tooling. Your primary desire is to be able to run the server right?

Moving forward with BS4 is huge. I propose the following criteria:

• Sphinx 2.0+
• Python 3.5+
• Continue supporting bootswatch "plug and play" theme customization.

The last one is particularly important in my opinion, since many users want to have "non-default bootstrap" but don't have enough Sphinx or frontend experience to actually change things.

I think we should make this non-backwards compatible and do a relatively significant overhaul. We can include an "upgrading to 1.x" document that outlines what options have changed or been removed.

We might want to do

1. Update tooling on master
2. Fork from there to a bs4 branch and then PR to there.

This will allow bugfixes on 0.* while we continue with the updates (unclear how long it will take). I can definitely get the tooling out either this week or over the weekend, but I won't have much free time to help other than review.

[jorisvandenbossche]

Thanks for the answers!

I'd definitely be up for changes to get the theme up to BS4.

Regarding the theme I have been working on in https://github.com/pandas-dev/pandas-sphinx-theme, I think the main questions for sphinx-bootstrap-theme is which parts of the things I described above you would be interested in (the BootstrapHTML5Translator, the navigation objects, the layout as option, ..)

Moving forward with BS4 is huge. I propose the following criteria:

Yes, I agree that is easier to do this in a non-backwards compatible manner (you could keep 0.x with the current version, and have 1.x with the BS4 version). Also agreed that at once we should bump the requirements for python/sphinx.

Your proposal to first update the tooling sounds good.