1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
|
(manual-environment)=
# 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](https://docs.conda.io/en/latest/), [mamba](https://github.com/mamba-org/mamba), or [virtualenv](https://virtualenv.pypa.io/).
## Pre-requisites
Before you start, ensure that you have the following installed:
- Python >= 3.9
- [Pandoc](https://pandoc.org/): we use `nbsphinx` to support notebook (`.ipynb`) files in the documentation, which requires [installing Pandoc](https://pandoc.org/installing.html) 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:
```console
$ 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:
```console
$ 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:
```console
$ 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:
```console
$ 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:
```console
$ 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:
```console
$ pytest
```
|
