Skip to content

Commit

Permalink
update component branch (#15)
Browse files Browse the repository at this point in the history 
* Change default logo alt text (pydata#1472)

* Default logo alt text only if no extra text

* change default logo

* use docstitle as default logo alt text

* update docs to reflect change

* Apply suggestions from code review

Co-authored-by: Daniel McCloy <dan@mccloy.info>

* use string formatting operator

* Update docs/user_guide/branding.rst

* docs fixes

* Update docs/user_guide/branding.rst

* add test

* Update pyproject.toml

* revert to original

---------

Co-authored-by: Daniel McCloy <dan@mccloy.info>
Co-authored-by: Rambaud Pierrick <12rambau@users.noreply.github.com>

* chore(i18n) catalan (pydata#1488)

i18n: Translate sphinx.po in ca

100% translated source file: 'sphinx.po'
on 'ca'.

Co-authored-by: transifex-integration[bot] <43880903+transifex-integration[bot]@users.noreply.github.com>

* Build(deps): Bump postcss and css-loader (pydata#1494)

Bumps [postcss](https://github.com/postcss/postcss) to 8.4.31 and updates ancestor dependency [css-loader](https://github.com/webpack-contrib/css-loader). These dependencies need to be updated together.


Updates `postcss` from 8.4.21 to 8.4.31
- [Release notes](https://github.com/postcss/postcss/releases)
- [Changelog](https://github.com/postcss/postcss/blob/main/CHANGELOG.md)
- [Commits](postcss/postcss@8.4.21...8.4.31)

Updates `css-loader` from 3.6.0 to 6.8.1
- [Release notes](https://github.com/webpack-contrib/css-loader/releases)
- [Changelog](https://github.com/webpack-contrib/css-loader/blob/master/CHANGELOG.md)
- [Commits](webpack-contrib/css-loader@v3.6.0...v6.8.1)

---
updated-dependencies:
- dependency-name: postcss
  dependency-type: indirect
- dependency-name: css-loader
  dependency-type: direct:development
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

* Revert "Build(deps): Bump postcss and css-loader" (pydata#1509)

Revert "Build(deps): Bump postcss and css-loader (pydata#1494)"

This reverts commit 185a37a.

* Update pst docs buttons (pydata#1502)

* call them button-links

* copy edit

* docs: link back to GitHub from PyPI metadata (pydata#1504)

This will add a "Source" link in the PyPI page.

* navigation_with_keys = False (pydata#1503)

* navigation_with_keys = False

* None -> False

* Apply suggestions from code review

---------

Co-authored-by: Daniel McCloy <dan@mccloy.info>

* fix: convert "stable" to actual version number (pydata#1512)

* convert "stable" to actual version number

* fix tests re: navigation_with_keys

* try bumping autoapi

* refactor: use nbsphinx as the default execution lib (pydata#1482)

* refactor: use nbsphinx as the default execution lib

* add nbstripout to the pre-commits'

* add pandoc to the readthedocs deps

* refactor: clean the notebook

* move the example to the correct folder

* fix: solve link issue

* install pandoc in the test environment

* fix: display of large table in executed cells

* avoid Userwarnings from matplotlib

* hide the matplotlib wrning management cell

* Update readthedocs.yml

* build: use pandoc_binary to install pandoc

* docs: add reference to pandoc in the setup

* update docs

* remove pypandoc_binary

* Update pyproject.toml

Co-authored-by: gabalafou <gabriel@fouasnon.com>

* ci: use back setup-pandoc

* Trigger CI build

---------

Co-authored-by: Gabriel Fouasnon <gabriel@fouasnon.com>

* BUG - Clear alt_text in conf.py (pydata#1471)

* comment out alt_text in conf.py

* set alt_text to empty string

* remove alt_text from conf.py

* fix: use 12rambau fork until it's merged with nikeee repo (pydata#1517)

* deps: drop support for Sphinx 5 (pydata#1516)

* remove ref to myst-nb

* update minimal supported version of sphinx

* Fix: (webpack.config.js) css-loader API change (pydata#1508)

* Fix: (webpack.config.js) css-loader API change

The build was broken in
<https://github.com/pydata/pydata-sphinx-theme/commit/185a37aa36820f77bffa4c87a772092e9e7cc380>/<https://github.com/pydata/pydata-sphinx-theme/pull/1494>.

This change fixes the build, and it seems to be in accordance with the
current API as described at <https://github.com/webpack-contrib/css-loader/blob/c6f36cf91ac61743a70e81cfb077faa0f8730ebe/README.md#boolean>.

Closes <pydata#1507>.

* dedup

* restore version bump

---------

Co-authored-by: Daniel McCloy <dan@mccloy.info>

* Fix duplicate HTML IDs (pydata#1425)

* Fix duplicate HTML IDs

* fix tests

* Do not animate the version admonitions colors. (pydata#1424)

Otherwise a delay has to be added to the accessibility color
contrast checks, to wait for the colors to fully transition.

* BUG - Remove redundant ARIA in breadcrumb navigation (pydata#1426)

* style(i18n): French Typo fixed (pydata#1430)

* Add the ability to add a center section to the footer (pydata#1432)

* Add a center section for the footer

* Add docs for footer_center

* Add a test site for the center footer

* test it in our own docs

* remove new test site

* add footer test

---------

Co-authored-by: Daniel McCloy <dan@mccloy.info>

* Build(deps): Bump actions/checkout from 3 to 4 (pydata#1433)

Bumps [actions/checkout](https://github.com/actions/checkout) from 3 to 4.
- [Release notes](https://github.com/actions/checkout/releases)
- [Changelog](https://github.com/actions/checkout/blob/main/CHANGELOG.md)
- [Commits](actions/checkout@v3...v4)

---
updated-dependencies:
- dependency-name: actions/checkout
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

* Add dropdown_text argument to generate_header_nav_html (pydata#1423)

* Add dropdown_text argument to generate_header_nav_html

* Add a test, fix typo in theme.conf and remove header_dropdown_text from docs/conf.py

* fixed?

---------

Co-authored-by: Daniel McCloy <dan@mccloy.info>

* fix: rollback ref and Id changes (pydata#1438)

* bump: version 0.13.3 → 0.14.0  (pydata#1440)

* bump version

* update version switcher

* back to dev

* fix: change the z-index of the dropdown (pydata#1442)

In order to be on top of the primary sidebar on small screens.

* fix: set the same background for dark/light (pydata#1443)

* fix: set the same background for dark/light
et the same background color for all state of the search field. It is currently only applied when hovered

* fix: wrong css selector

* Update src/pydata_sphinx_theme/assets/styles/components/_search.scss

* Update src/pydata_sphinx_theme/assets/styles/components/_search.scss

* Fix duplicate HTML IDs

* fix tests

* unique_html_id

* backwards-compat generate_header_nav_html

* feedback review

* update fixture

* ughhhh...caching

* code cleanup

* fix test snapshot

* put comment inside def

---------

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: Denis Bitouzé <dbitouze@wanadoo.fr>
Co-authored-by: Stuart Mumford <stuart@cadair.com>
Co-authored-by: Daniel McCloy <dan@mccloy.info>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Alenka Frim <AlenkaF@users.noreply.github.com>
Co-authored-by: Rambaud Pierrick <12rambau@users.noreply.github.com>

* chore: build the devcontainer automatically in codespace (pydata#1483)

* chore: build the devcontainer automaticallyin codespace

* refactor: lint

* add pandoc to the environment

* Fix font color in search input box (pydata#1524)

* Fix color

* Use --pst-color-text-base

* docs: add DecentralChain (pydata#1528)

Co-authored-by: jourlez <josuecr.288@gmail.com>

* Updates for file src/pydata_sphinx_theme/locale/en/LC_MESSAGES/sphinx.po in ru [Manual Sync] (pydata#1527)

i18n: Translate sphinx.po in ru [Manual Sync]

96% of minimum 20% translated source file: 'sphinx.po'
on 'ru'.

Sync of partially translated files: 
untranslated content is included with an empty translation 
or source language content depending on file format

Co-authored-by: transifex-integration[bot] <43880903+transifex-integration[bot]@users.noreply.github.com>

* ignore transient errors in windows build CI (pydata#1520)

* use warning list

* clean up notebook

* refactor to pass on all platforms?

* simplify

* fix logic

* iterate backwards

* fix plaform detection? also don't log unnecessarily�[H

* ignore empty string warnings

* remove notebook metawarning

* Revert "remove notebook metawarning"

This reverts commit 42f4672.

* try again

* debug the mysterious empty warning

* escape color codes

* import

* triage by intermittency, not by platform; better var names

* simplify

* fix list.remove

* undo what I broke

* Update tests/utils/check_warnings.py

* refactor: remove extention on component set-up (pydata#1529)

* use event.key for search shortcut (pydata#1525)

* use event.key for search shortcut

* suggestions from review

* caps lock

---------

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: gabalafou <gabriel@fouasnon.com>
Co-authored-by: Daniel McCloy <dan@mccloy.info>
Co-authored-by: transifex-integration[bot] <43880903+transifex-integration[bot]@users.noreply.github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Ned Batchelder <ned@nedbatchelder.com>
Co-authored-by: Adam Porter <adam@alphapapa.net>
Co-authored-by: Denis Bitouzé <dbitouze@wanadoo.fr>
Co-authored-by: Stuart Mumford <stuart@cadair.com>
Co-authored-by: Alenka Frim <AlenkaF@users.noreply.github.com>
Co-authored-by: Harutaka Kawamura <hkawamura0130@gmail.com>
Co-authored-by: jourlez <josuecr.288@gmail.com>
  • Loading branch information
@12rambau @gabalafou
@drammock @transifex-integration @dependabot @nedbat @alphapapa @dbitouze @Cadair @AlenkaF @harupy @jourlez
12 people committed Oct 20, 2023
1 parent f87e543 commit 77e1bfc
Show file tree
Hide file tree
Showing 37 changed files with 825 additions and 255 deletions.
11 changes: 11 additions & 0 deletions .devcontainer/devcontainer.json
View file
@@ -0,0 +1,11 @@
// container instruction for codespace users
{
"name": "Python 3",
"image": "mcr.microsoft.com/devcontainers/python:1-3.10-bullseye",
"features": {
"ghcr.io/devcontainers-contrib/features/nox:2": {},
"ghcr.io/devcontainers-contrib/features/pre-commit:2": {},
"ghcr.io/rocker-org/devcontainer-features/pandoc:1": {}
},
"postCreateCommand": "pre-commit install"
}
3 changes: 3 additions & 0 deletions .github/workflows/tests.yml
View file
Expand Up @@ -137,6 +137,9 @@ jobs:
runs-on: ${{ matrix.os }}
steps:
- uses: actions/checkout@v4
# waiting for https://github.com/nikeee/setup-pandoc/pull/8
# using 12rambau fork until then
- uses: 12rambau/setup-pandoc@test
- name: Setup Python
uses: actions/setup-python@v4
with:
Expand Down
5 changes: 5 additions & 0 deletions .pre-commit-config.yaml
View file
Expand Up @@ -38,3 +38,8 @@ repos:
rev: v1.1.1
hooks:
- id: doc8

- repo: "https://github.com/kynan/nbstripout"
rev: "0.5.0"
hooks:
- id: nbstripout
1 change: 1 addition & 0 deletions docs/community/setup.md
View file
Expand Up @@ -42,6 +42,7 @@ To simplify this process, we use a few helper tools:
- [The Sphinx Theme Builder](https://sphinx-theme-builder.readthedocs.io/en/latest/) compiles web assets in an automated way.
- [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.
- [pandoc](https://pandoc.org/) the universal document converter.

In particular, `nox` can be used to automatically create isolated local development environments with all the correct packages installed to work on the theme.
The rest of this guide focuses on using `nox` to start with a basic environment.
Expand Down
22 changes: 13 additions & 9 deletions docs/community/topics/manual-dev.md
View file
Expand Up @@ -12,30 +12,34 @@ This is optional, but it's best to start with a fresh development environment so

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
## Install dependencies

First clone this repository from the `pydata` organization, or from a fork that you have created:
You must install `sphinx-theme-builder` and Pandoc.

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
$ git clone https://github.com/pydata/pydata-sphinx-theme
$ cd pydata-sphinx-theme
$ pip install "sphinx-theme-builder[cli]"
```

## Install the `sphinx-theme-builder`
We use `nbsphinx` to support notebook (.ipynb) files in the documentation, which requires [installing Pandoc](https://pandoc.org/installing.html) at a system level (or within a Conda environment).

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):
## Clone the repository locally

First clone this repository from the `pydata` organization, or from a fork that you have created:

```console
$ pip install sphinx-theme-builder[cli]
$ git clone https://github.com/pydata/pydata-sphinx-theme
$ cd pydata-sphinx-theme
```

## 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]
$ pip install -e ".[dev]"
```

Note that the `sphinx-theme-builder` will automatically install a local copy of `nodejs` for building the theme's assets.
Expand Down
40 changes: 21 additions & 19 deletions docs/conf.py
View file
Expand Up @@ -34,15 +34,15 @@
"sphinx_design",
"sphinx_copybutton",
"autoapi.extension",
# custom extentions
"_extension.gallery_directive",
"_extension.component_directive",
# For extension examples and demos
"myst_parser",
"ablog",
"jupyter_sphinx",
"matplotlib.sphinxext.plot_directive",
"myst_nb",
"sphinxcontrib.youtube",
# "nbsphinx", # Uncomment and comment-out MyST-NB for local testing purposes.
"nbsphinx",
"numpydoc",
"sphinx_togglebutton",
"jupyterlite_sphinx",
Expand All @@ -67,18 +67,18 @@
sitemap_locales = [None]
sitemap_url_scheme = "{link}"

# -- Internationalization ----------------------------------------------------

# specifying the natural language populates some key tags
language = "en"

# -- MyST options ------------------------------------------------------------

# This allows us to use ::: to denote directives, useful for admonitions
myst_enable_extensions = ["colon_fence", "linkify", "substitution"]
myst_heading_anchors = 2
myst_substitutions = {"rtd": "[Read the Docs](https://readthedocs.org/)"}

# -- Internationalization ----------------------------------------------------

# specifying the natural language populates some key tags
language = "en"

# -- Ablog options -----------------------------------------------------------

blog_path = "examples/blog/index"
Expand All @@ -100,19 +100,21 @@

# Define the version we use for matching in the version switcher.
version_match = os.environ.get("READTHEDOCS_VERSION")
release = pydata_sphinx_theme.__version__
# If READTHEDOCS_VERSION doesn't exist, we're not on RTD
# If it is an integer, we're in a PR build and the version isn't correct.
# If it's "latest" → change to "dev" (that's what we want the switcher to call it)
if not version_match or version_match.isdigit() or version_match == "latest":
# For local development, infer the version to match from the package.
release = pydata_sphinx_theme.__version__
if "dev" in release or "rc" in release:
version_match = "dev"
# We want to keep the relative reference if we are in dev mode
# but we want the whole url if we are effectively in a released version
json_url = "_static/switcher.json"
else:
version_match = "v" + release
version_match = f"v{release}"
elif version_match == "stable":
version_match = f"v{release}"

html_theme_options = {
"external_links": [
Expand Down Expand Up @@ -160,28 +162,28 @@
"logo": {
"text": "PyData Theme",
"image_dark": "_static/logo-dark.svg",
"alt_text": "PyData Theme",
},
"use_edit_page_button": True,
"show_toc_level": 1,
"navbar_align": "left", # [left, content, right] For testing that the navbar items align properly
"navbar_center": ["version-switcher", "navbar-nav"],
# "show_nav_level": 2,
"announcement": "https://raw.githubusercontent.com/pydata/pydata-sphinx-theme/main/docs/_templates/custom-template.html",
"show_version_warning_banner": True,
# "show_nav_level": 2,
"navbar_center": ["version-switcher", "navbar-nav"],
# "navbar_start": ["navbar-logo"],
# "navbar_end": ["theme-switcher", "navbar-icon-links"],
# "navbar_persistent": ["search-button"],
# "primary_sidebar_end": ["custom-template.html", "sidebar-ethical-ads.html"],
# "article_footer_items": ["test.html", "test.html"],
# "content_footer_items": ["test.html", "test.html"],
"footer_start": ["copyright.html"],
"footer_center": ["sphinx-version.html"],
# "secondary_sidebar_items": ["page-toc.html"], # Remove the source buttons
# "primary_sidebar_end": ["custom-template", "sidebar-ethical-ads"],
# "article_footer_items": ["test", "test"],
# "content_footer_items": ["test", "test"],
"footer_start": ["copyright"],
"footer_center": ["sphinx-version"],
# "secondary_sidebar_items": ["page-toc"], # Remove the source buttons
"switcher": {
"json_url": json_url,
"version_match": version_match,
},
"navigation_with_keys": False,
# "search_bar_position": "navbar", # TODO: Deprecated - remove in future version
}

Expand Down
2 changes: 2 additions & 0 deletions docs/examples/gallery.md
View file
Expand Up @@ -43,4 +43,6 @@ Thanks for your support!
link: https://docs.pyvista.org
- title: Pastas
link: https://pastas.readthedocs.io/
- title: DecentralChain
link: https://docs.decentralchain.io/en/master/
```
151 changes: 151 additions & 0 deletions docs/examples/pydata.ipynb
View file
@@ -0,0 +1,151 @@
{
"cells": [
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# PyData Library Styles\n",
"\n",
"This theme has built-in support and special styling for several major visualization libraries in the PyData ecosystem.\n",
"This ensures that the images and output generated by these libraries looks good for both light and dark modes.\n",
"Below are examples of each that we use as a benchmark for reference.\n",
"\n",
"## Pandas"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"import string\n",
"\n",
"import numpy as np\n",
"import pandas as pd\n",
"\n",
"rng = np.random.default_rng()\n",
"data = rng.standard_normal((100, 26))\n",
"df = pd.DataFrame(data, columns=list(string.ascii_lowercase))\n",
"df"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Matplotlib"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"import matplotlib.pyplot as plt\n",
"\n",
"fig, ax = plt.subplots()\n",
"ax.scatter(df[\"a\"], df[\"b\"], c=df[\"b\"], s=3)"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"rng = np.random.default_rng()\n",
"data = rng.standard_normal((3, 100))\n",
"fig, ax = plt.subplots()\n",
"ax.scatter(data[0], data[1], c=data[2], s=3)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Plotly\n",
"\n",
"The HTML below shouldn't display, but it uses RequireJS to make sure that all\n",
"works as expected. If the widgets don't show up, RequireJS may be broken."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"import plotly.io as pio\n",
"import plotly.express as px\n",
"import plotly.offline as py\n",
"\n",
"pio.renderers.default = \"notebook\"\n",
"\n",
"df = px.data.iris()\n",
"fig = px.scatter(df, x=\"sepal_width\", y=\"sepal_length\", color=\"species\", size=\"sepal_length\")\n",
"fig"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Xarray\n",
"\n",
"Here we demonstrate `xarray` to ensure that it shows up properly."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"import xarray as xr\n",
"data = xr.DataArray(\n",
" np.random.randn(2, 3),\n",
" dims=(\"x\", \"y\"),\n",
" coords={\"x\": [10, 20]}, attrs={\"foo\": \"bar\"}\n",
" )\n",
"data"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## ipyleaflet\n",
"\n",
"`ipyleaflet` is a **Jupyter**/**Leaflet** bridge enabling interactive maps in the Jupyter notebook environment. this demonstrate how you can integrate maps in your documentation."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"from ipyleaflet import Map, basemaps\n",
"\n",
"# display a map centered on France\n",
"m = Map(basemap=basemaps.Esri.WorldImagery, zoom=5, center=[46.21, 2.21])\n",
"m"
]
}
],
"metadata": {
"kernelspec": {
"display_name": "Python 3",
"language": "python",
"name": "python3"
},
"language_info": {
"name": "python",
"version": "3.10.8"
}
},
"nbformat": 4,
"nbformat_minor": 2
}

0 comments on commit 77e1bfc

Please sign in to comment.