Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

update #14

Closed
wants to merge 21 commits into from
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
8fc9287
Change default logo alt text (#1472)
gabalafou Sep 27, 2023
95f46a1
chore(i18n) catalan (#1488)
transifex-integration[bot] Sep 29, 2023
185a37a
Build(deps): Bump postcss and css-loader (#1494)
dependabot[bot] Oct 5, 2023
feb2bc2
Revert "Build(deps): Bump postcss and css-loader" (#1509)
drammock Oct 13, 2023
78213ca
Update pst docs buttons (#1502)
gabalafou Oct 16, 2023
3dd0bef
docs: link back to GitHub from PyPI metadata (#1504)
nedbat Oct 16, 2023
36847fc
navigation_with_keys = False (#1503)
gabalafou Oct 16, 2023
2acf82b
fix: convert "stable" to actual version number (#1512)
drammock Oct 17, 2023
78793e5
refactor: use nbsphinx as the default execution lib (#1482)
12rambau Oct 17, 2023
f31fee4
BUG - Clear alt_text in conf.py (#1471)
gabalafou Oct 17, 2023
4cff3e5
fix: use 12rambau fork until it's merged with nikeee repo (#1517)
12rambau Oct 17, 2023
4fe4d7b
deps: drop support for Sphinx 5 (#1516)
12rambau Oct 17, 2023
bcfcc85
Fix: (webpack.config.js) css-loader API change (#1508)
alphapapa Oct 17, 2023
fda4087
Fix duplicate HTML IDs (#1425)
gabalafou Oct 17, 2023
0e84397
chore: build the devcontainer automatically in codespace (#1483)
12rambau Oct 18, 2023
bb50976
Fix font color in search input box (#1524)
harupy Oct 18, 2023
59d8b2b
docs: add DecentralChain (#1528)
12rambau Oct 19, 2023
161b957
Updates for file src/pydata_sphinx_theme/locale/en/LC_MESSAGES/sphinx…
transifex-integration[bot] Oct 19, 2023
0802c96
ignore transient errors in windows build CI (#1520)
drammock Oct 19, 2023
f8847eb
refactor: remove extention on component set-up (#1529)
12rambau Oct 19, 2023
1dcdada
use event.key for search shortcut (#1525)
gabalafou Oct 19, 2023
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions .devcontainer/devcontainer.json
Original file line number Diff line number Diff line change
@@ -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
Original file line number Diff line number Diff line change
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
Original file line number Diff line number Diff line change
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
Original file line number Diff line number Diff line change
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
Original file line number Diff line number Diff line change
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
42 changes: 22 additions & 20 deletions docs/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -34,18 +34,18 @@
"sphinx_design",
"sphinx_copybutton",
"autoapi.extension",
"_extension.gallery_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",
"sphinx_favicon",
# custom extentions
"_extension.gallery_directive",
]

# Add any paths that contain templates here, relative to this directory.
Expand All @@ -66,18 +66,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 @@ -99,19 +99,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 @@ -159,28 +161,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
Original file line number Diff line number Diff line change
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
Original file line number Diff line number Diff line change
@@ -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
}
Loading
Loading