If you are reading this guide because you have decided to contribute to the Scylla Sphinx Theme, thank you! We appreciate your contribution and hope that this handbook will answer any questions you may have.
This project’s Python side is managed with Poetry. It combines several things in one tool:
Keeping track of Python dependencies, including ones required only for development and tests.
Initializing and managing a virtual environment.
Packaging the theme into a package for PyPI (Python Package Index).
Such package can be installed with
pip install and other tools.
To initialize a Python development environment for this project:
Make sure you have Python version 3.7 or later installed.
Initialize a virtual environment with:
This will create an environment outside of the project directory, somewhere under
You’ll see the path in installation logs.
Activate the virtual environment for current shell session:
Alternatively, if you use PyCharm, you can configure the project to use this environment as the default Python interpreter. PyCharm doesn’t detect Poetry (yet), so just use the “virtualenv” option and provide the full path to the environment.
docs folder contains a sample project with the Sphinx theme already installed.
To preview the theme locally:
Open a new console prompt and clone the project.
git clone https://github.com/scylladb/sphinx-scylladb-theme.git
Build the docs.
cd docs make preview
The previous command should generate a
docs/_build/dirhtml directory. To preview the docs, open http://127.0.0.1:5500/ with your preferred browser.
The frontend static files of this project are managed with webpack. It combines several things in one tool:
Installing third-party node modules.
The original static files are located under the folder
To build the minimized static files for this project:
Make sure you have Node.js LTS installed.
Build the static files with:
npm run build
This will create minified static files under the
poetry run pytest tests
You need a PyPi account and be a project maintainer to release new theme versions.
To publish a new version of the theme to PyPi, run the following script:
Behind the scenes,
deploy.sh executes the following logic:
Checks if the local git URL matches the original repository to prevent you from releasing from a personal fork.
Checks if the local contents differ from the remote master branch.
Increases the package’s version patch with the command
poetry version patch.
Builds the package with the command
Asks for your PyPI username and password and publishes the package to PyPI with
After publishing the package, you should see the new release listed on PyPI.
To increase the minor version, run
poetry version minor before
To increase the major version, run
poetry version major before