DOCS: Update front page, contributing doc, and gallery code

.github/workflows/lighthouserc.json

@@ -1,7 +1,7 @@
 {
   "ci": {
     "collect": {
-      "staticDistDir": "./docs/_build/html/demo/kitchen-sink",
+      "staticDistDir": "./docs/_build/html/examples/kitchen-sink",
       "settings": {
         "skipAudits": ["canonical"]
       }

.gitignore

@@ -63,7 +63,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
-docs/demo/generated/
+docs/examples/generated/
 
 # PyBuilder
 target/

docs/_static/contributors.yaml

@@ -0,0 +1,24 @@
+- header: "@bollwyvl"
+  image: https://avatars.githubusercontent.com/u/45380
+  link: https://github.com/bollwyvl
+- header: "@jarrodmillman"
+  image: https://avatars.githubusercontent.com/u/123428
+  link: https://github.com/jarrodmillman
+- header: "@hoetmaaiers"
+  image: https://avatars.githubusercontent.com/u/468045
+  link: https://github.com/hoetmaaiers
+- header: "@jorisvandenbossche"
+  image: https://avatars.githubusercontent.com/u/1020496
+  link: https://github.com/jorisvandenbossche
+- header: "@damianavila"
+  image: https://avatars.githubusercontent.com/u/1640669
+  link: https://github.com/damianavila
+- header: "@drammock"
+  image: https://avatars.githubusercontent.com/u/1810515
+  link: https://github.com/drammock
+- header: "@choldgraf"
+  image: https://avatars.githubusercontent.com/u/1839645
+  link: https://github.com/choldgraf
+- header: "@12rambau"
+  image: https://avatars.githubusercontent.com/u/12596392
+  link: https://github.com/12rambau

docs/_static/gallery.yaml

@@ -0,0 +1,52 @@
+# Metadata to create our example gallery. This YAML file does two things:
+#
+# 1. Used by `generate_gallery_images.py` to take snapshots of each item and place an image in `gallery`.
+# 2. Used by our Gallery Grid directive to create the grid on our `examples/gallery.md` page.
+#
+# title: The title of each gallery item
+# website: The website that will be used to create a snapshot of this item.
+#    An image will be placed in docs/_static/gallery/{sanitized_title}.png
+# img-bottom: The location where img-bottoms will be placed for each entry by generate_gallery_img-bottoms.py
+#    This should follow the form shown above and is roughly the same for all items.
+- title: Pandas
+  website: https://pandas.pydata.org/docs/
+  img-bottom: ../_static/gallery/pandas.png
+- title: NumPy
+  website: https://numpy.org/doc/stable/
+  img-bottom: ../_static/gallery/numpy.png
+- title: SciPy
+  website: https://docs.scipy.org/doc/scipy/
+  img-bottom: ../_static/gallery/scipy.png
+- title: Bokeh
+  website: https://docs.bokeh.org/en/latest/
+  img-bottom: ../_static/gallery/bokeh.png
+- title: CuPy
+  website: https://docs.cupy.dev/en/stable/index.html
+  img-bottom: ../_static/gallery/cupy.png
+- title: PyVista
+  website: https://docs.pyvista.org
+  img-bottom: ../_static/gallery/pyvista.png
+- title: MNE-Python
+  website: https://mne.tools/stable/index.html
+  img-bottom: ../_static/gallery/mne-python.png
+- title: NetworkX
+  website: https://networkx.org/documentation/stable/
+  img-bottom: ../_static/gallery/networkx.png
+- title: Fairlearn
+  website: https://fairlearn.org/main/about/
+  img-bottom: ../_static/gallery/fairlearn.png
+- title: Jupyter Book
+  website: https://jupyterbook.org/en/stable/intro.html
+  img-bottom: ../_static/gallery/jupyter_book.png
+- title: Binder
+  website: https://mybinder.readthedocs.io/en/latest/index.html
+  img-bottom: ../_static/gallery/binder.png
+- title: Jupyter
+  website: https://docs.jupyter.org/en/latest/
+  img-bottom: ../_static/gallery/jupyter.png
+- title: MegEngine
+  website: https://www.megengine.org.cn/doc/stable/en/index.html
+  img-bottom: ../_static/gallery/megengine.png
+- title: Feature-engine
+  website: https://feature-engine.readthedocs.io/
+  img-bottom: ../_static/gallery/feature-engine.png

docs/community/contributors.md

@@ -0,0 +1,20 @@
+# 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 initial design of the theme logo.

docs/community/index.md

@@ -0,0 +1,29 @@
+---
+myst:
+  html_meta:
+    "description lang=en": "How to become a contributor to the pydata-sphinx-theme."
+---
+
+# Community 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
+manual
+
+```
+
+```{toctree}
+:maxdepth: 2
+:caption: About the project
+
+contributors
+policies
+inspiration
+```

docs/community/inspiration.md

@@ -0,0 +1,30 @@
+# 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
+```

docs/contribute/setup.md → docs/community/setup.md

@@ -4,6 +4,22 @@ This section covers the simplest way to get started developing this theme locall
 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).
 
+## 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.
+
+The sections below cover the steps to do this in more detail.
+
 ## Clone the repository
 
 First off you'll need your own copy of the `pydata-sphinx-theme` codebase.

docs/contribute/index.md → docs/community/structure.md

@@ -1,26 +1,4 @@
----
-myst:
-  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.
+# Structure of this theme
 
 ## Location and structure of documentation
 
@@ -46,13 +24,3 @@ The CSS and JS for this theme are built for the browser from `src/pydata_sphinx_
 
   - 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
-policies
-manual
-```

docs/contribute/topics.md → docs/community/topics.md

@@ -184,21 +184,21 @@ If a Sphinx release causes major breaking changes for our users, and we do not h
 
 ## Update our kitchen sink documents
 
-The [kitchen sink reference](../demo/kitchen-sink/index.rst) is for demonstrating as much syntax and style for Sphinx builds as possible.
+The [kitchen sink reference](../examples/kitchen-sink/index.rst) is for demonstrating as much syntax and style for Sphinx builds as possible.
 It is copied directly from the [`sphinx-themes.org` documentation](https://sphinx-themes.org/) so that we use standardized reference docs compared with other communities.
 The source files for these pages are stored [in the `sphinx-themes.org` repository](https://github.com/sphinx-themes/sphinx-themes.org/raw/master/sample-docs/kitchen-sink/).
 
 If you'd like to update our local files with any changes that have been made to the `sphinx-themes.org` files, simply copy/paste those changes into our local files and make a commit.
 
 Here's a list of our pages and where they come from in `sphinx-themes.org`:
 
-- [`index.rst`](../demo/kitchen-sink/index.rst) ([source](https://github.com/sphinx-themes/sphinx-themes.org/blob/master/sample-docs/kitchen-sink/index.rst))
-- [`api.rst`](../demo/kitchen-sink/api.rst) ([source](https://github.com/sphinx-themes/sphinx-themes.org/blob/master/sample-docs/kitchen-sink/api.rst))
-- [`lists-and-tables.rst`](../demo/kitchen-sink/lists-and-tables.rst) ([source](https://github.com/sphinx-themes/sphinx-themes.org/blob/master/sample-docs/kitchen-sink/lists-and-tables.rst))
-- [`paragraph-markup.rst`](../demo/kitchen-sink/paragraph-markup.rst) ([source](https://github.com/sphinx-themes/sphinx-themes.org/blob/master/sample-docs/kitchen-sink/paragraph-markup.rst))
+- [`index.rst`](../examples/kitchen-sink/index.rst) ([source](https://github.com/sphinx-themes/sphinx-themes.org/blob/master/sample-docs/kitchen-sink/index.rst))
+- [`api.rst`](../examples/kitchen-sink/api.rst) ([source](https://github.com/sphinx-themes/sphinx-themes.org/blob/master/sample-docs/kitchen-sink/api.rst))
+- [`lists-and-tables.rst`](../examples/kitchen-sink/lists-and-tables.rst) ([source](https://github.com/sphinx-themes/sphinx-themes.org/blob/master/sample-docs/kitchen-sink/lists-and-tables.rst))
+- [`paragraph-markup.rst`](../examples/kitchen-sink/paragraph-markup.rst) ([source](https://github.com/sphinx-themes/sphinx-themes.org/blob/master/sample-docs/kitchen-sink/paragraph-markup.rst))
 
 :::{note}
-To demonstrate extra styles and syntax that is not in the Kitchen sink, use the [Theme Elements reference](../demo/theme-elements.md).
+To demonstrate extra styles and syntax that is not in the Kitchen sink, use the [Theme Elements reference](../examples/theme-elements.md).
 :::
 
 ## Update the example gallery
@@ -220,7 +220,7 @@ If you'd like to build these images locally to preview in the theme, follow thes
 2. Execute the gallery generation script from the repository root:
 
    ```
-   $ python ./docs/scripts/generate_gallery_text.py
+   $ python ./docs/scripts/generate_gallery_images.py
    ```
 
 :::{note}
@@ -265,3 +265,9 @@ For more details, see:
 
 - https://git-scm.com/docs/git-config#Documentation/git-config.txt-blameignoreRevsFile
 - https://github.com/pydata/pydata-sphinx-theme/pull/713
+
+## The `gallery-grid` directive
+
+There are a few places where we use `sphinx-design` to generate "galleries" of grids with structured text and images.
+We've created a little Sphinx directive to make it easier to repeat this process in our documentation and to avoid repeating ourselves too much.
+It is located in the `docs/scripts/` folder in a dedicated module, and re-used throughout our documentation.