Set up a manual development environment#
If you prefer not to use automation tools like tox
, or want to have more control over the specific version of packages that you’d like installed,
you may set your local development environment manually.
To do so, follow the instructions on this page.
Create a new development environment#
This is optional, but it’s best to start with a fresh development environment so that you’ve isolated the packages that you’re using for this repository.
To do so, use a tool like conda, mamba, or virtualenv.
Pre-requisites#
Before you start, ensure that you have the following installed:
Python >= 3.9
Pandoc: we use
nbsphinx
to support notebook (.ipynb
) files in the documentation, which requires installing Pandoc at a system level (or within a Conda environment).
Clone the repository locally#
First clone this repository from the pydata
organization, or from a fork that you have created:
$ git clone https://github.com/pydata/pydata-sphinx-theme
$ cd pydata-sphinx-theme
Install this theme locally#
Next, install this theme locally so that we have the necessary dependencies to build the documentation and testing suite:
$ pip install -e ".[dev]"
Note that the sphinx-theme-builder
will automatically install a local copy of nodejs
for building the theme’s assets.
This will be placed in a .nodeenv
folder.
Build the documentation#
To manually build the documentation, run the following command:
$ sphinx-build docs docs/_build/html
Compile web assets (JS/CSS)#
To compile the JavaScript and CSS assets for the theme, run the following command:
$ stb compile
This will compile everything in the src/pydata_sphinx_theme/assets
folder and place them in the appropriate places in our theme’s folder structure.
Start a live server to build and serve your documentation#
To manually open a server to watch your documentation for changes, build them, and display them locally in a browser, run this command:
$ stb serve docs --open-browser
Manually run the tests#
To manually run the tests for this theme, first set up your environment locally, and then run:
$ pytest