Description
Description / Summary
Our current setup commits the compiled CSS + hashes directly into our repository. The biggest downside to this is that merge conflicts happen any time somebody merges a PR when another person has a PR open that also modifies CSS or JS.
We're also using the web-compile package to compile our web assets. This is quite lightweight and useful, though we do miss some of the benefit of the NPM ecosystem, which has a lot more functionality that is designed for building web assets.
Recently there has emerged a new theme development tool called sphinx-theme-builder. This is a Python package that bundles a version of nodejs along with it, so you don't need to go through the hassle of setting up your own node environment. It also has a command line set of tools that let you quickly perform compilation steps via webpack, so you can use the full webpack ecosystem, vendor fonts/packages/etc as you like but without needing to do a bunch of javascript installs. Because the compilation is part of the build step, it means that you do not need to check your compiled CSS/JS assets into the repository, you can do that at build time, so you don't generate merge conflicts whenever you change the JS/CSS compiled assets. Finally, the theme builder is a nice step towards defining a standard sphinx theme structure, which will make it easier to port patterns and share development between the themes that are out there.
Implementation details
The PyData theme recently switched over to using this new build system, and it has worked out pretty nicely over there. Here's the PR where @pradyunsg did that work: