Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
15 changed files
with
528 additions
and
486 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1 +1,2 @@ | ||
v{{ version }} | ||
<!-- A small template snippet for theme testing --> | ||
TEST: v{{ version }} |
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,58 @@ | ||
--- | ||
html_meta: | ||
"description lang=en": "How to become a contributor to the pydata-sphinx-theme." | ||
--- | ||
|
||
# Contribute | ||
|
||
These pages contain information about how you can get up-and-running with a development version of this theme, and how you can contribute to the project. | ||
|
||
## Workflow for contributing changes | ||
|
||
We follow a [typical GitHub workflow](https://guides.github.com/introduction/flow/) | ||
of: | ||
|
||
- create a personal fork of this repo | ||
- create a branch | ||
- open a pull request | ||
- fix findings of various linters and checks | ||
- work through code review | ||
|
||
For each pull request, the demo site is built and deployed to make it easier to review | ||
the changes in the PR. To access this, click on the "ReadTheDocs" preview in the CI/CD jobs. | ||
|
||
## Location and structure of documentation | ||
|
||
The documentation for this theme is in the `docs/` folder. | ||
It is structured as a [Sphinx documentation site](https://sphinx-doc.org). | ||
The content is written in a combination of reStructuredText and MyST Markdown. | ||
|
||
## Location and structure of CSS/JS assets | ||
|
||
The CSS and JS for this theme are built for the browser from `src/*` with | ||
[webpack](https://webpack.js.org/). The main entrypoints are: | ||
|
||
- CSS: `src/scss/index.scss` | ||
|
||
- the main part of the theme assets | ||
- customizes [Bootstrap](https://getbootstrap.com/) with [Sass](https://sass-lang.com) | ||
- points to the `font-face` of vendored web fonts, but does not include their | ||
CSS `@font-face` declaration | ||
|
||
- JS: `src/js/index.js` | ||
|
||
- provides add-on Bootstrap features, as well as some custom navigation behavior | ||
|
||
- webpack: `webpack.config.js` | ||
|
||
- captures the techniques for transforming the JS and CSS source files in | ||
`src/` into the production assets in `pydata_sphinx_theme/static/` | ||
|
||
**For more information** about developing this theme, see the sections below and in the left sidebar. | ||
|
||
```{toctree} | ||
:maxdepth: 2 | ||
setup | ||
topics | ||
manual | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,75 @@ | ||
(manual-environment)= | ||
|
||
# Set up a manual development environment | ||
|
||
If you prefer not to use automation tools like `nox`, you may also manually set up a development environment locally. | ||
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/). | ||
|
||
## 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 the `sphinx-theme-builder` | ||
|
||
We use the `sphinx-theme-builder` to install `nodejs` locally and to compile all CSS and JS assets needed for the theme. | ||
Install it like so (note the `cli` option so that we can run it from the command line): | ||
|
||
```console | ||
$ pip install sphinx-theme-builder[cli] | ||
``` | ||
|
||
## 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 | ||
``` | ||
|
||
## Run the tests | ||
|
||
To manually run the tests for this theme, first set up your environment locally, and then run: | ||
|
||
```console | ||
$ pytest | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,150 @@ | ||
# Get started with development | ||
|
||
This section covers the simplest way to get started developing this theme locally so that you can contribute. | ||
It uses automation and as few steps as possible to get things done. | ||
If you'd like to do more operations manually, see [](manual.md). | ||
|
||
## Clone the repository | ||
|
||
First off you'll need your own copy of the `pydata-sphinx-theme` codebase. | ||
You can clone it for local development like so: | ||
|
||
1. **Fork the repository** so you have your own copy on GitHub. | ||
See [the GitHub forking guide](https://docs.github.com/en/get-started/quickstart/fork-a-repo) for more information. | ||
2. **Clone the repository locally** so that you have a local copy to work from: | ||
|
||
```console | ||
$ git clone https://github.com/{{ YOUR USERNAME }}/pydata-sphinx-theme | ||
$ cd pydata-sphinx-theme | ||
``` | ||
|
||
## Install your tools | ||
|
||
Building a Sphinx site uses a combination of Python and Jinja to manage HTML, SCSS, and Javascript. | ||
To simplify this process, we use a few helper tools: | ||
|
||
- [The Sphinx Theme Builder](https://sphinx-theme-builder.readthedocs.io/en/latest/) to automatically perform compilation of web assets. | ||
- [pre-commit](https://pre-commit.com/) for automatically enforcing code standards and quality checks before commits. | ||
- [nox](https://nox.thea.codes/), for automating common development tasks. | ||
|
||
In particular, `nox` can be used to automatically create isolated local development environments with all of the correct packages installed to work on the theme. | ||
The rest of this guide focuses on using `nox` to start with a basic environment. | ||
|
||
```{seealso} | ||
The information on this page covers the basics to get you started, for information about manually compiling assets, see [](manual.md). | ||
``` | ||
|
||
### Setup `nox` | ||
|
||
To start, install `nox`: | ||
|
||
```console | ||
$ pip install nox | ||
``` | ||
|
||
You can call `nox` from the command line in order to perform common actions that are needed in building the theme. | ||
`nox` operates with isolated environments, so each action has its own packages installed in a local director (`.nox`). | ||
For common development actions, you'll simply need to use `nox` and won't need to set up any other packages. | ||
|
||
### Setup `pre-commit` | ||
|
||
`pre-commit` allows us to run several checks on the codebase every time a new Git commit is made. | ||
This ensures standards and basic quality control for our code. | ||
|
||
Install `pre-commit` with the following command: | ||
|
||
```console | ||
$ pip install pre-commit | ||
``` | ||
|
||
then navigate to this repository's folder and activate it like so: | ||
|
||
```console | ||
$ pre-commit install | ||
``` | ||
|
||
This will install the necessary dependencies to run `pre-commit` every time you make a commit with Git. | ||
|
||
## Build the documentation | ||
|
||
Now that you have `nox` installed and cloned the repository, you should be able to build the documentation locally. | ||
|
||
To build the documentation with `nox`, run the following command: | ||
|
||
```console | ||
$ nox -s docs | ||
``` | ||
|
||
This will install the necessary dependencies and build the documentation located in the `docs/` folder. | ||
They will be placed in a `docs/_build/html` folder. | ||
If the docs have already been built, it will only build new pages that have been updated. | ||
You can open one of the HTML files there to preview the documentation locally. | ||
|
||
### Change content and re-build | ||
|
||
Now that you've built the documentation, edit one of the source files to see how the documentation updates with new builds. | ||
|
||
1. **Make an edit to a page**. For example, add a word or fix a typo on any page. | ||
2. **Rebuild the documentation** with `nox -s docs` | ||
|
||
It should go much faster this time, because `nox` is re-using the old environment, and because Sphinx has cached the pages that you didn't change. | ||
|
||
## Compile the CSS/JS assets | ||
|
||
The source files for CSS and JS assets are in `src/pydata_sphinx_theme/assets`. | ||
These are then built and bundled with the theme (e.g., `scss` is turned into `css`). | ||
|
||
To compile the CSS/JS assets with `nox`, run the following command: | ||
|
||
```console | ||
$ nox -s compile | ||
``` | ||
|
||
This will compile all assets and place them in the appropriate folder to be used with documentation builds. | ||
|
||
```{note} | ||
Compiled assets are **not committed to git**. | ||
The `sphinx-theme-builder` will bundle these assets automatically when we make a new release, but we do not manually commit these compiled assets to git history. | ||
``` | ||
|
||
## Run a development server | ||
|
||
You can combine the above two actions and run a development server so that changes to `src/` are automatically bundled with the package, and the documentation is immediately reloaded in a live preview window. | ||
|
||
To run the development server with `nox`, run the following command: | ||
|
||
```console | ||
$ nox -s docs-live | ||
``` | ||
|
||
When working on the theme, saving changes to any of these directories: | ||
|
||
- `src/js/index.js` | ||
- `src/scss/index.scss` | ||
- `docs/**/*.rst` | ||
- `docs/**/*.py` | ||
|
||
will cause the development server to do the following: | ||
|
||
- bundle/copy the CSS, JS, and vendored fonts | ||
- regenerate the Jinja2 macros | ||
- re-run Sphinx | ||
|
||
## Run the tests | ||
|
||
This theme uses `pytest` for its testing, with a lightweight fixture defined | ||
in the `test_build.py` script that makes it easy to run a Sphinx build using | ||
this theme and inspect the results. | ||
|
||
In addition, we use [pytest-regressions](https://pytest-regressions.readthedocs.io/en/latest/) | ||
to ensure that the HTML generated by the theme is what we'd expect. This module | ||
provides a `file_regression` fixture that will check the contents of an object | ||
against a reference file on disk. If the structure of the two differs, then the | ||
test will fail. If we _expect_ the structure to differ, then delete the file on | ||
disk and run the test. A new file will be created, and subsequent tests will pass. | ||
|
||
To run the tests with `nox`, run the following command: | ||
|
||
```console | ||
$ nox -s test | ||
``` |
Oops, something went wrong.