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/custom-template.html

@@ -1,6 +1,6 @@
 <div class="sidebar-message">
-    This is a community-supported theme.
-    If you'd like to contribute,
-    <a href="https://github.com/pydata/pydata-sphinx-theme">check out our GitHub repository</a>
-    Your contributions are welcome!
+  This is a community-supported theme.
+  If you'd like to contribute,
+  <a href="https://github.com/pydata/pydata-sphinx-theme">check out our GitHub repository</a>
+  Your contributions are welcome!
 </div>

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",
@@ -107,6 +107,14 @@
     },
 }
 
+html_sidebars = {
+    "contribute/index": [
+        "search-field",
+        "sidebar-nav-bs",
+        "custom-template",
+    ],  # This ensures we test for custom sidebars
+}
+
 
 html_context = {
     "github_user": "pandas-dev",
@@ -115,6 +123,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/pydata_sphinx_theme/assets/*` with
+[webpack](https://webpack.js.org/). The main entrypoints are:
+
+- CSS: `src/pydata_sphinx_theme/assets/styles/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/pydata_sphinx_theme/assets/scripts/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/pydata_sphinx_theme/assets/*` into the production assets in `src/theme/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,76 @@
+(manual-environment)=
+
+# Set up a manual development environment
+
+If you prefer not to use automation tools like `nox`, or want to have more control over the specific version of packages that you'd like like installed, 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
+```