Closed chrisjsewell closed 3 years ago
FYI @choldgraf @pradyunsg @AakashGfude @mmcky, following my musings in #31, I've move away from the "dynamic" SCSS compilation (i.e. during sphinx-build), and instead implemented https://github.com/executablebooks/scss-compile. This allows for a pre-commit compilation of the CSS, which ensures it is synced with the SCSS (and so both are present in the repo). This ticks the boxes:
I've also added the (CSS only) tabbed
directive 😄, and set up the docs/tox to build for multiple themes in the same branch (see the Development section of the README):
sphinx-rtd-theme
: https://sphinx-panels--32.org.readthedocs.build/en/32/#tabbed-contentsphinx-book-theme
: https://106-260360729-gh.circle-artifacts.com/0/html/index.html#tabbed-contentLastly, this now also includes conf.py
configurable CSS variables, via creation of a separate CSS file, that just contains some CSS custom properties. This allows for configuration of certain variables (like tab label color) without the need to create custom CSS overrides.
Wheee! There's lots of cool stuff here, and I like almost all of it.
The bit that concerns me is the use of pre-commit to compile the SCSS.
I think the first bullet is a deal breaker. :)
I think a good approach here would be to treat the SCSS like a C extension -- include the source code in the source distribution and the compiled form (i.e. CSS) in the generated wheel.
It should be doable already with setuptools (I'd suggest writing a little plugin to make it reusable across packages) and I'm checking how Thomas feels about adding a build step to flit
(https://github.com/takluyver/flit/issues/119#issuecomment-687779285).
Maybe this should become a meta issue about "how to handle SCSS", where we discuss and standardize the approach across all the executablebooks projects?
With all due respect I disagree lol
I think a good approach here would be to treat the SCSS like a C extension -- include the source code in the source distribution and the compiled form (i.e. CSS) in the generated wheel.
This increases the complexity of the package and precludes interactive development workflows
It raises the minimum required effort to make bug fixes changes from "change the code correctly" to "change the code correctly and regenerate the CSS"
If you install pre-commit you don't need to worry about this, it just does it automatically
each PR will unconditionally have different generated CSS, so merging any one PR will cause all other existing PRs to conflict with it
I haven't come across this issue, will have a test now
I haven't come across this issue, will have a test now
I guess this is what you meant: #35, #36. Basically you always need to merge branches into master which are up-to-date
Hmm, yeh I'll have a play around with compiling during distribution & development only then
I think being able to use a project directly from git (to test the master version) without needing to compile is also valuable.
Regarding the PR workflow: do yo mean that any PR will need to be updated after another PR is merged because of the name change? (so eg you can't merge two PRs directly after each other) (that's a problem for pydata-sphinx-theme then as well ...)
do yo mean that any PR will need to be updated after another PR is merged because of the name change? (so eg you can't merge two PRs directly after each other)
Yup!
I think being able to use a project directly from git (to test the master version) without needing to compile is also valuable.
Indeed.
I think what we have here is a choice among multiple options where each has a different tradeoff, so we should really make an issue somewhere (is meta the right place?) to aggregate "what would be nice to have" as well as all the possible approaches, compare them and make a choice for all our projects based off that. :)
that's a problem for pydata-sphinx-theme then as well
quite possibly, as I think you are pretty much doing what I'm doing; in terms of creating a hashed CSS file (and deleting any old ones) via a pre-commit, and failing if it does not already exist.
You can easily test these there:
is meta the right place?
yep I think so
just to finish my thoughts here, basically as you say each option seems to have an annoying tradeoff. Putting aside JavaScript compilation for now, my ideal goals are:
Using SCSS as the CSS source, which is linted in the pre-commit
Having hashed CSS end up in the built documentation
Having a way of allowing users to configure certain variables (colors/font-size), without having to add their own custom CSS overrides. sphinx allows for these .css_t
Jinja templates, but I'm not really a fan of them, because obviously this means now you can't use SCSS and/or lint/compress the CSS. I think the solution I've implemented here works pretty well: dynamic creation of a small additional CSS file, with some custom properties declared in the root namespace.
Being able to do live development; whereby you can have the documentation in the browser, which updates when your messing around with the any of the Python code, SCSS or RST/Markdown pages
Not having the SCSS compiler as an install dependency. It's not necessarily a bad option, sphinx after all is a build system; however, the available packages are both not ideal; python-libsass adds a large install overhead, because it has C-bindings, pyScss is lightweight, but not very well maintained, has some bugs, and lacks some key features. Plus it doesn't work great with how sphinx handles theme packages.
(Having the SCSS and sourcemaps in the built documentation would be nice, but low priority)
Compiled CSS is now included as part of the distribution, with pre-commit ensuring that the CSS is consistent with the SCSS. This removes pyScss as a dependency, and should mitigate any issues with faulty CSS compilation.