Develop this theme#

This page describes the tooling used during development of this theme. It also serves as a reference for the various commands that you would use when working on this theme.

Overview#

The codebase contains Python code, Jinja2-based HTML pages, Sass stylesheets, Scss stylesheets and Javascript code. The following tools are used in developing the theme:

  • nox is used for automating development tasks.

  • Webpack-based build pipeline is used to process the Sass, Scss and Javascript files.

  • sphinx-autobuild is used to provide live-reloading pages when working on the theme.

  • pre-commit is used for running the linters.

Theme structure#

This theme follows the sphinx-theme-builder filesystem layout.

Initial Setup#

To work on this project, you need to have git 2.17+ and Python 3.7+. You also need to be on a platform that is officially supported by NodeJS 18.

  1. Clone this project using git:

    git clone https://github.com/zclab/bulma-sphinx-theme.git
cd bulma-sphinx-theme

  2. Install the project’s development workflow runner:

    pip install nox

  3. Install pre-commit, pre-commit allows us to run several checks on the codebase every time a new Git commit is made, install it with the following command :

    pip install pre-commit

    then navigate to this repository’s folder and activate it like so:

    pre-commit install

    This will install the necessary dependencies to run pre-commit every time you make a commit with Git.

With the above step, you’re all set for working on this project.

Build the theme#

Now that you have nox installed and cloned the repository, you should be able to build the documentation locally.

Local Development Server#

The following command serve this project’s documentation locally, using sphinx-autobuild. This will open the generated documentation page in your browser.

nox -s docs-live

The server also watches for changes made to the documentation (docs/) or theme (src/), which will trigger a rebuild. Once the build is completed, server will automagically reload any open pages using livereload.

Generate Documentation#

The following commands generates the documentation into the build/docs folder. This (mostly) does the same thing as nox -s docs-live, except it invokes sphinx-build instead of sphinx-autobuild.

nox -s docs

Code Linting#

Run the linters, as configured with pre-commit.

nox -s lint

Last updated on Jan 16, 2024.

previous

Blogs with ABlog

next

Examples