Sphinx ScyllaDB Theme 1.0 is now released 🥳
Learn more
Menu

Contribute to the Theme¶

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.

Configuring a Python environment¶

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:

  1. Make sure you have Python version 3.7 or later installed.

  2. Install Poetry.

  3. Initialize a virtual environment with:

    poetry install
    

    This will create an environment outside of the project directory, somewhere under ~/Library/Caches/pypoetry/virtualenvs/. You’ll see the path in installation logs.

  4. Activate the virtual environment for current shell session:

    poetry shell
    

    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.

Previewing the theme locally¶

The docs folder contains a sample project with the Sphinx theme already installed.

To preview the theme locally:

  1. Open a new console prompt and clone the project.

    git clone https://github.com/scylladb/sphinx-scylladb-theme.git
    
  2. Build the docs.

    cd docs
    make preview
    
  3. 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.

Building the frontend¶

The frontend static files of this project are managed with webpack. It combines several things in one tool:

  • Installing third-party node modules.

  • Combining JavaScript and CSS in a single file.

  • Minifying CSS and JavaScript files.

The original static files are located under the folder src.

To build the minimized static files for this project:

  1. Make sure you have Node.js LTS installed.

  2. Build the static files with:

npm run build

This will create minified static files under the sphinx_scylladb_theme/static.

Running unit tests¶

Run:

poetry run pytest tests

Publishing the theme to PyPi¶

Note

You need a PyPi account and be a project maintainer to release new theme versions.

All the documentation projects receives new patches when the theme is released on PyPi. The script automatically increases the package’s version and will ask you for the PyPi username and password.

./deploy.sh

The script automatically increases the package’s version and will ask you for the PyPi username and password.

After publishing the package, you should see the new release listed on PyPI.