ScyllaDB University Live | Free Virtual Training Event
Learn more
ScyllaDB Documentation Logo Documentation
  • Server
  • Cloud
  • Tools
    • ScyllaDB Manager
    • ScyllaDB Monitoring Stack
    • ScyllaDB Operator
  • Drivers
    • CQL Drivers
    • DynamoDB Drivers
  • Resources
    • ScyllaDB University
    • Community Forum
    • Tutorials
Download
ScyllaDB Docs ScyllaDB Sphinx Theme Contribute Contribute to the theme

Caution

You're viewing documentation for a previous version of ScyllaDB Sphinx Theme. Switch to the latest stable version.

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 3.7 or later installed.

  2. Install Poetry.

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.

To publish a new version of the theme to PyPi, run the following script:

./deploy.sh

To increase the minor version, run poetry version minor before ./deploy.

To increase the major version, run poetry version major before ./deploy.

Behind the scenes, deploy.sh executes the following logic:

  1. Checks if the local git URL matches the original repository to prevent you from releasing from a personal fork.

  2. Checks if the local contents differ from the remote master branch.

  3. Increases the package’s version patch with the command poetry version patch.

  4. Builds the package with the command poetry build.

  5. Asks for your PyPI username and password and publishes the package to PyPI with poetry publish.

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

Was this page helpful?

PREVIOUS
Scylla docs contributor’s handbook
  • Create an issue
  • Edit this page

On this page

  • Contribute to the theme
    • Configuring a Python environment
    • Previewing the theme locally
    • Building the frontend
    • Running unit tests
    • Publishing the theme to PyPi
ScyllaDB Sphinx Theme
  • 1.2
    • 1.8
    • 1.7
    • 1.6
    • 1.5
    • 1.4
    • 1.3
    • 1.2
    • 1.1
  • Getting started
    • Toolchain
    • Installation
  • Configuration
    • Template options
    • Page options
    • Multiversion options
    • Markdown support
    • Redirections support
    • Search support
    • Troubleshooting
  • Commands
  • Deployment
    • Production deployment
    • Pull requests previews
  • Examples
    • Admonitions
    • Collapse
    • Code blocks
    • Glossary
    • Headings
    • Hero box
    • Includes
    • Images
    • Links
    • Lists
    • Panel box
    • Substitutions
    • Tables
    • Tabs
    • Text
    • TOC
    • Topic box
    • Versions
  • Upgrade guides
    • Migrating from 1.1 to 1.2
    • Migrating from 1.0 to 1.1
    • Migrating from 0.x to 1.0
    • Changelog
  • Contribute
    • Contribute to the documentation
    • Contribute to the theme
    • Source Code
Docs Tutorials University Contact Us About Us
© 2025 ScyllaDB | Terms of Service | Privacy Policy | ScyllaDB, and ScyllaDB Cloud, are registered trademarks of ScyllaDB, Inc.
Last updated on 01 Apr 2025.
Powered by Sphinx 7.4.7 & ScyllaDB Theme 1.8.6
Ask AI