pydata · 12rambau · Oct 19, 2023 · Oct 19, 2023 · Oct 19, 2023 · Oct 20, 2023
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
@@ -1,7 +1,7 @@
 // container instruction for codespace users
 {
   "name": "Python 3",
-  "image": "mcr.microsoft.com/devcontainers/python:1-3.10-bullseye",
+  "image": "mcr.microsoft.com/devcontainers/python:1-3.11-bullseye",
   "features": {
     "ghcr.io/devcontainers-contrib/features/nox:2": {},
     "ghcr.io/devcontainers-contrib/features/pre-commit:2": {},

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -5,7 +5,7 @@ default_language_version:
 
 repos:
   - repo: https://github.com/pre-commit/mirrors-prettier
-    rev: v2.7.1
+    rev: v3.0.3
     hooks:
       - id: prettier
         # Exclude the HTML, since it doesn't understand Jinja2

diff --git a/docs/_static/custom-icon.js b/docs/_static/custom-icon.js
diff --git a/docs/community/contributors.md b/docs/community/contributors.md
diff --git a/docs/community/contributors.rst b/docs/community/contributors.rst
@@ -0,0 +1,23 @@
+Contributors to this theme
+==========================
+
+This theme is supported and developed by various members of `the PyData community <https://pydata.org>`__.
+
+Collaborators on the repository
+-------------------------------
+
+Here is a grid of collaborators on our GitHub repository.
+We don't yet have formal "team definitions" so this is mostly a reflection of who has commit rights to the repository.
+
+.. gallery-grid:: ../_static/contributors.yaml
+    :class-card: text-center
+
+Financial support
+-----------------
+
+Support and development for this theme has been funded by one `NumFocus Small Development Grant <https://numfocus.org/programs/small-development-grants>`__ on behalf of several communities in the PyData ecosystem.
+
+Theme logo
+----------
+
+Thanks to `@drammock <https://github.com/drammock>`__ for the initial design of the theme logo.
diff --git a/docs/community/index.md b/docs/community/index.md
diff --git a/docs/community/index.rst b/docs/community/index.rst
@@ -0,0 +1,25 @@
+Contributor Guide
+=================
+
+These pages contain information about the community that leads, supports, and develops this theme, including how you can contribute to the project.
+
+.. toctree::
+    :maxdepth: 2
+    :caption: Contributor guide
+
+    setup
+    structure
+    topics/index
+
+.. toctree::
+    :caption: Team practices
+    :glob:
+
+    practices/*
+
+.. toctree::
+    :maxdepth: 2
+    :caption: About the project
+
+    contributors
+    inspiration
diff --git a/docs/community/inspiration.md b/docs/community/inspiration.md
diff --git a/docs/community/inspiration.rst b/docs/community/inspiration.rst
@@ -0,0 +1,31 @@
+Inspiration for design and UX
+=============================
+
+To build this theme we drew inspiration from other great projects on the web that we would like to acknowledge here.
+When making new decisions about design and UI/UX, we often consult these themes to see what they're doing.
+
+.. gallery-grid::
+    :grid-columns: 1 2 2 3
+    :class-container: text-center
+
+    - title: "**GitBook**"
+      link: https://docs.gitbook.com/
+      image: https://avatars.githubusercontent.com/u/7111340?s=280&v=4
+    - title: "**Metaflow**"
+      image: https://repository-images.githubusercontent.com/209120637/00b39080-1ddc-11ea-8710-59b484540700
+      link: https://docs.metaflow.org/
+    - title: "**Furo**"
+      image: https://avatars.githubusercontent.com/u/3275593?v=4
+      link: https://pradyunsg.me/furo/quickstart
+    - title: "**Docker**"
+      link: https://docs.docker.com/
+      image: https://www.docker.com/wp-content/uploads/2022/03/vertical-logo-monochromatic.png
+    - title: "**PyTorch**"
+      link: https://pytorch.org/docs/stable/index.html
+      image: https://pytorch.org/assets/images/pytorch-logo.png
+    - title: "**Docasaurus**"
+      link: https://docusaurus.io/docs
+      image: https://d33wubrfki0l68.cloudfront.net/c088b7acfcf11100903c44fe44f2f2d7e0f30531/47727/img/docusaurus.svg
+    - title: "**Material for MkDocs**"
+      link: https://squidfunk.github.io/mkdocs-material/getting-started/
+      image: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/src/.icons/logo.svg
diff --git a/docs/community/practices/merge.md → docs/community/practices/merge.rst b/docs/community/practices/merge.md → docs/community/practices/merge.rst
@@ -1,4 +1,5 @@
-# Merge and review policy
+Merge and review policy
+=======================
 
 Our policy for merging and reviewing describes how we review one another's work, and when we allow others to merge changes into our main codebase.
 It tries to balance a few goals:
@@ -16,7 +17,8 @@ We follow these guidelines to achieve these goals:
 - It's important to share information, so give your best effort at telling others about the work that you're doing.
 - It's best to discuss and agree on important decisions at a high level before implementation, so give the best effort at providing time and invitation for others to provide feedback.
 
-## Policy for moderate changes
+Policy for moderate changes
+---------------------------
 
 These are changes that make modest changes to new or existing functionality, but that aren't going to significantly change the default behavior of the theme, user configuration, etc.
 This is the majority of changes that we make.
@@ -31,14 +33,16 @@ They can be merged when the above conditions are met, and one of these things ha
 - The PR has at least one approval from a core maintainer that isn't the PR author
 - The PR author has signaled their intent to merge unless there are objections, and 48 hours have passed since that comment.
 
-## Policy for major new features and breaking changes
+Policy for major new features and breaking changes
+--------------------------------------------------
 
 These are changes that significantly alter the experience of the user, or that add significant complexity to the codebase.
 
 All the above, but PRs **must** have approval from at least one other core maintainer before merging.
 In addition, the PR author should put extra effort into ensuring that the relevant stakeholders are notified about a change, so they can gauge its impact and provide feedback.
 
-## Policy For minor changes and bugfixes
+Policy For minor changes and bugfixes
+-------------------------------------
 
 These are small changes that might be noticeable to the user, but in a way that is clearly an improvement.
 They generally shouldn't touch too many lines of code.

diff --git a/docs/community/practices/release.md → docs/community/practices/release.rst b/docs/community/practices/release.md → docs/community/practices/release.rst
@@ -1,8 +1,10 @@
-# Making releases
+Making releases
+===============
 
-(policies:release)=
+.. _policies-release:
 
-## Our goals
+Our goals
+---------
 
 Our release policy describes how we decide when to make a new public release of the theme so that other projects may use new features and improvements.
 It tries to balance these goals:
@@ -11,33 +13,37 @@ It tries to balance these goals:
 - Do not surprise people (especially with negative surprises) and provide time for projects to provide feedback about upcoming features.
 - Minimize the toil and complexity associated with releases, and reduce information silos and bottlenecks associated with them.
 
-(releases:when)=
+.. _releases-when:
 
-## When to make a release
+When to make a release
+----------------------
 
 Anybody is encouraged to make a new release if:
 
 - It has been more than a month since the last release.
 - OR a significant change has been made to our code that warrants a release.
-- AND there are no open issues with a [{guilabel}`block-release`](https://github.com/pydata/pydata-sphinx-theme/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Ablock-release) label.
+- AND there are no open issues with a :guilabel:`impact: block-release` label.
 
-### Release candidates
+Release candidates
+^^^^^^^^^^^^^^^^^^
 
-If a release includes complex or many changes (especially in JavaScript), make a `release candidate` and ask for feedback from users.
+If a release includes complex or many changes (especially in JavaScript), make a ``release candidate`` and ask for feedback from users.
 This is important because we do not test much of the CSS and JavaScript-based functionality in our testing infrastructure.
 After a week or so, if there are no blocking issues that have been opened since the Release Candidate, we can make a full release.
 
-## Process for making a release
+Process for making a release
+----------------------------
 
 This theme uses GitHub tags and releases to automatically push new releases to
 PyPI.
 Follow these steps to make a release:
 
-- (optionally) **Create a [GitHub milestones](https://github.com/pydata/pydata-sphinx-theme/milestones)** to organize the issues that should be resolved as part of a new release.
-- **Decide if it's time** to make a release be reading [](releases:when) and decide if it is time for a release.
-- **Copy the release checklist into a new issue**. We have [a release checklist in our wiki](https://github.com/pydata/pydata-sphinx-theme/wiki/Release-checklist#release-instructions).
+- (optionally) **Create a `GitHub milestones <https://github.com/pydata/pydata-sphinx-theme/milestones>`__** to organize the issues that should be resolved as part of a new release.
+- **Decide if it's time** to make a release be reading `releases-when`_ and decide if it is time for a release.
+- **Copy the release checklist into a new issue**. We have `a release checklist in our wiki <https://github.com/pydata/pydata-sphinx-theme/wiki/Release-checklist#release-instructions>`_.
 - **Complete the checklist**. That's it!
 
-## Choosing a version increment
+Choosing a version increment
+----------------------------
 
-We use [semantic versioning](https://semver.org/) to decide whether it's a major, minor, or patch bump. Before we have released `1.0`, treat minor versions as breaking releases, and patch versions as feature / patch releases. **If this is a release candidate**, tag it like `0.1rc1`.
+We use `semantic versioning <https://semver.org/>`__ to decide whether it's a major, minor, or patch bump. Before we have released ``1.0``, treat minor versions as breaking releases, and patch versions as feature / patch releases. **If this is a release candidate**, tag it like ``0.1rc1``.
diff --git a/docs/community/practices/versions.md b/docs/community/practices/versions.md
diff --git a/docs/community/practices/versions.rst b/docs/community/practices/versions.rst
@@ -0,0 +1,42 @@
+Supported Python and Sphinx versions
+====================================
+
+Python and Sphinx are the two primary dependencies of this theme.
+We have particular practices for deciding which versions of these we support (especially Sphinx, which tends to release breaking changes).
+
+Supported Python versions
+-------------------------
+
+For releases of Python, we aim to follow this approach [1]:
+
+    For a new major/minor release of this theme, we support any minor Python versions released in the last 3.5 years (42 months), as defined in `the EOL schedule for Python <https://endoflife.date/python>`__ [2].
+
+We define "support" as testing against each of these versions so that users can be assured they will not trigger any bugs.
+
+For example, if we made a minor release tomorrow, we'd `look at the EOL schedule for Python <https://endoflife.date/python>`__ and support all the versions that fall within a 3.5-year window.
+
+Supported Sphinx versions
+-------------------------
+
+For supported versions of Sphinx, we aim to follow this approach:
+
+    We support the latest released version of Sphinx that is **older than 6 months**.
+    We unofficially support earlier released versions of Sphinx, but may increase the lower-bound in our dependency pin without warning if needed [2].
+
+When a new pre-release of Sphinx is released, we should follow these steps:
+
+- Ensure that our tests are passing. We run our tests with any **pre-releases** of Sphinx, so we can test major errors quickly and make the necessary changes.
+- `Look at the Sphinx Changelog <https://www.sphinx-doc.org/en/master/changes.html>`__ and make sure there are no changes that might break things that aren't captured by our tests.
+- `Look at the deprecated API changes <https://www.sphinx-doc.org/en/master/extdev/deprecated.html>`__ and make sure there are no changes that might break things that aren't captured by our tests.
+- `Look at the docutils changelog <https://docutils.sourceforge.io/RELEASE-NOTES.html>`__ in case there's a new docutils version supported that breaks something.
+
+.. note::
+
+    This theme does not pin the upper version of Sphinx that it supports.
+    If a Sphinx release causes major breaking changes for our users, and we do not have the capacity to update our code and release a fix, we may temporarily pin the upper bound of Sphinx we support until this is fixed.
+
+.. rubric:: Footnotes
+
+.. [1] Our support for Python versions is inspired by `NEP 029 <https://numpy.org/neps/nep-0029-deprecation_policy.html>`__.
+
+.. [2] These policies are goals, not promises. We are a volunteer-led community with limited time. Consider these sections to be our intention, but we recognize that we may not always be able to meet these criteria if we cannot do so. We welcome contributions from others to help us more sustainably meet these goals!