DOCS: refactor developer docs

.github/workflows/tests.yml

@@ -135,7 +135,7 @@ jobs:
           verbose: true
 
       - name: Run the accessibility audit
-        run: python docs/a11y.py --no-serve
+        run: python docs/scripts/a11y.py --no-serve
 
       # Check the audit for threshold values
       # TODO: write this someplace after a PR is merged, and load?

docs/_templates/navbar-version.html

@@ -1 +1,2 @@
-v{{ version }}
+<!-- A small template snippet for theme testing -->
+TEST: v{{ version }}

docs/conf.py

@@ -34,11 +34,12 @@
 # ones.
 
 extensions = [
+    "jupyter_sphinx",
+    "myst_parser",
+    "numpydoc",
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
-    "numpydoc",
-    "myst_parser",
-    "jupyter_sphinx",
+    "sphinxext.rediraffe",
 ]
 
 # -- Internationalization ------------------------------------------------
@@ -64,11 +65,6 @@
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
-html_sidebars = {
-    "contributing": ["search-field", "custom-template"],
-    "changelog": [],
-}
-
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -79,7 +75,11 @@
 
 html_theme_options = {
     "external_links": [
-        {"url": "https://pandas.pydata.org/pandas-docs/stable/", "name": "Pandas Docs"}
+        {
+            "url": "https://github.com/pydata/pydata-sphinx-theme/releases",
+            "name": "Changelog",
+        },
+        {"url": "https://pandas.pydata.org/pandas-docs/stable/", "name": "Pandas Docs"},
     ],
     "github_url": "https://github.com/pydata/pydata-sphinx-theme",
     "twitter_url": "https://twitter.com/pandas_dev",
@@ -115,6 +115,10 @@
     "doc_path": "docs",
 }
 
+rediraffe_redirects = {
+    "contributing.rst": "contribute/index.rst",
+}
+
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".

docs/contribute/index.md

@@ -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
+```

docs/contribute/manual.md

@@ -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
+```

docs/contribute/setup.md

@@ -0,0 +1,158 @@
+# 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.
+
+Alternatively, you can invoke the built-in Python [http.server](https://docs.python.org/3/library/http.server.html#module-http.server) with:
+
+```console
+$ python -m http.server -d _build/html/
+```
+
+This will print a local URL that you can open in a browser to explore the HTML files.
+
+### 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
+```