This theme makes efforts to be as extensible as possible.
In this guide we will learn how to modify docutils nodes before rendering, tweak CSS and apply javascript hacks.
We will need:
- nodejs v9.11.1 or superior
- npm 5.8.0 or superior
# clone the repo
git clone https://github.com/gabrielfalcao/sphinx-bulma-theme.git
cd sphinx-bulma-theme
npm install --dev
Sphinx has its own opinion of what CSS classes should be in what elements. The theme attempts to inject the appropriate classes in certain nodes through :py:func:`sphinx_bulma_theme.bulmanize_documentation`.
But that's not enough.
To bridge the gap between bulma styles and Sphinx's optionated CSS classes this theme uses special CSS and Javascript.
Don't worry it's not as bad as it sounds.
Looking at the source tree we can spot 2 files:
sphinx_bulma_theme/sphinx-bulma.src.sass
sphinx_bulma_theme/sphinx-bulma.src.js
The good news: Bulma is build on sass so this theme makes little effort in extending it.
To build the CSS file run:
make sass
Under the hood it will run:
node-sass --include-path scss sphinx_bulma_theme/sphinx-bulma.src.sass sphinx_bulma_theme/static/css/theme.css
The good news: ES6 support :)
To build the JS file run:
make webpack
Under the hood it will run:
export NODE_ENV=production
export NODE_PATH=.:./node_modules:./sphinx_bulma_theme:$NODE_PATH
webpack -p
We will modify the file sphinx_bulma_theme/__init__.py
.
The execution entrypoint we will look for is :py:func:`~sphinx_bulma_theme.bulmanize_documentation`
.. seealso:: :py:func:`sphinx_bulma_theme.add_classes_to_node` and :py:func:`~sphinx_bulma_theme.process_admonition_node`