👌 IMPROVE: Move from CSS to SCSS #31
Conversation
The SCSS is compiled within the sphinx build, and the CSS is output filename includes the hash, to ensure cache invalidation on updates. Lastly, all files are rewritten, if a CSS hash changes, to allow for sphinx-autobuild to work correctly (in tox.ini)
|
@choldgraf @pradyunsg @AakashGfude you might want to have a look at this, as it's a prelude to changing sphinx-book-theme in the same way. |
chrisjsewell
changed the title
|
Also my sass game has upped a few levels, looking through the bootstrap repo 🤓 |
|
My suggestion would be to forfeit keeping master installable via git, omitting the generated file from the repo and only adding the "original" sources here. That's also what I'm doing in https://pradyunsg.me/furo. |
I'm not sure what you mean by this? None of the generated CSS is part of the repo, only the source SCSS |
|
@chrisjsewell nice work. The hash encoding is also looking neat. |
Ah, I meant:
Basically, there'd be a compile step between the source repository and the final distributions that get published on PyPI. I've opted for a Gulp-based pipeline over on the project I linked to (which lets me use popular/canonical implementations of the tools, instead of depending on ports). |
|
Ok, I'm going to merge this, to record the changes. But I might play around with pre-packaging with webpack, gulp, parcel, etc |
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: - No installation dependency on an SCSS compiler, meaning also no potential issues with SCSS compilation for users. - You don't have to implement an overly "heavy" web-bundler setup, like weppack or gulp - It still works with tox + sphinx-autobuild, for live development that updates on code/SCSS/docs changes - Hashed files, to ensure cache invalidation for new CSS - Later possibility for CSS -> SCSS mapping implementation. 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): - With `sphinx-rtd-theme`: https://sphinx-panels--32.org.readthedocs.build/en/32/#tabbed-content - With `sphinx-book-theme`: https://106-260360729-gh.circle-artifacts.com/0/html/index.html#tabbed-content Lastly, this now also includes `conf.py` configurable CSS variables, *via* creation of a separate CSS file, that just contains some [CSS custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties). This allows for configuration of certain variables (like tab label color) without the need to create custom CSS overrides.
The goals were:
.md,.rst,etc) and style files (i.e..scss)sphinx-panels does not contain any JS, and so I have not directly considered that.
The changes were:
FutureWarningwith pyscss that appears in build stdout, but the fix has been merged and hopefully should be released soon. pyscss does also currently preclude the addition of source maps 😢The other option considered was to pre-compile the scss to css with a pre-commit hook (to ensure the css is kept consistent).
This negates the requirement for a sass compiler install dependency.
But I was having a look at this in https://github.com/executablebooks/pre-commit-scss, and its not trivial (dealing with git) and would be more difficult to get working with
sphinx-autobuildA note on to other implementation re CSS, for future discussion:
Sphinx offers a templating functionality, whereby
css_tare first processed by jinja. This allows for configuration based CSS, e.g. used in insipid-sphinx-theme. It's an interesting use case, however I don't like that this then prohibits good CSS development practices like those used above. If desired, one could think about confining such configuration to a single SCSS fragment, which is written dynamically (to override a default) before compilation.pydata-sphinx-theme uses webpack to pre-compile JS/CSS (see its guide). This is a more mature standard, but the drawback is that it adds a larger development dependency overhead, and does not fit in well (at least currently) with sphinx-autobuild "live development" or allow for configurational CSS.
Edit: there is a live rebuild feature using yarn through: webpack.dev.js, but yeh it just adds a lot of overhead for a purely python package 🤔