PyData Sphinx Theme

https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1
Admin
The PyData Sphinx Theme is a clean, Bootstrap-based Sphinx theme providing responsive design,...
Tokens:121,197
Snippets:1,455
Trust Score:8.3
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install pre-commit hooks

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/community/setup.html

Navigate to the repository and install the pre-commit hooks. This ensures checks run automatically on Git commits.

```bash
$ pre-commit install

```

--------------------------------

### Install Theme Dependencies

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/_sources/community/topics/manual-dev.md

Install the theme locally with its development dependencies using pip in editable mode.

```bash
$ pip install -e ".[dev]"
```

--------------------------------

### Navigate to Blog Example

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/_sources/user_guide/ablog.md

Provides a button to link to an example blog index page. Use this to direct users to your blog's main page.

```jinja
..\examples\blog\index.html
:color: primary
Go to the blog
```

--------------------------------

### Install tox for Development

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/_sources/community/setup.md

Install the tox tool, which automates common development tasks and manages isolated environments for building the theme.

```console
$ pip install tox
```

--------------------------------

### GitHub Link Examples

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/_sources/user_guide/theme-elements.md

Examples of various GitHub URL formats that are automatically shortened.

```text
https://github.com
```

```text
https://github.com/pydata
```

```text
https://github.com/pydata/pydata-sphinx-theme
```

```text
https://github.com/pydata/pydata-sphinx-theme/pull/1012
```

```text
https://github.com/orgs/pydata/projects/2
```

--------------------------------

### Option List Examples

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/examples/kitchen-sink/lists.html

Demonstrates various ways to format command-line options and their descriptions.

```rst
-a
    
command-line option “a”
```

```rst
-b file
    
options can have arguments and long descriptions
```

```rst
--long
    
options can be long also
```

```rst
--input=file
    
long options can also have arguments
```

```rst
--very-long-option
    
The description can also start on the next line.
The description may contain multiple body elements, regardless of where it starts.
```

```rst
-x, -y, -z
    
Multiple options are an “option group”.
```

```rst
-v, --verbose
    
Commonly-seen: short & long options.
```

```rst
-1 file, --one=file, --two file
    
Multiple options with arguments.
```

```rst
/V
    
DOS/VMS-style options too
```

--------------------------------

### Add Assets via Setup Function

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/_sources/user_guide/static_assets.md

Add CSS and JavaScript files, or raw JavaScript, using `app.add_css_file` and `app.add_js_file` within the Sphinx `setup()` function. Paths are relative to `html_static_path`.

```python
html_static_path = ["_static"]

def setup(app):
  app.add_css_file("mycss.css")
  app.add_js_file("myjs.js")

  # Add raw JavaScript
  rawjs = """
  let a = "foo";
  console.log(a + " bar")
  """
  app.add_js_file(None, body=rawjs)
```

--------------------------------

### Install with pip

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/_sources/user_guide/install.rst

Install the pydata-sphinx-theme package using pip. This is the standard method for most Python projects.

```console
$ pip install pydata-sphinx-theme
```

--------------------------------

### Key and Menu Selection Examples

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/examples/kitchen-sink/generic.html

Demonstrates roles for key bindings and menu selections.

```rst
``⌘`+`⇧`+`M``
```

```rst
`menuselection`
```

```rst
`menuselection`
```

--------------------------------

### GitLab Link Examples

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/_sources/user_guide/theme-elements.md

Examples of various GitLab URL formats that are automatically shortened.

```text
https://gitlab.com
```

```text
https://gitlab.com/gitlab-org
```

```text
https://gitlab.com/gitlab-org/gitlab
```

```text
https://gitlab.com/gitlab-org/gitlab/-/issues/375583
```

--------------------------------

### Install pre-commit for Code Quality

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/_sources/community/setup.md

Install the pre-commit tool to automatically run code standards and quality checks before each Git commit.

```console
$ pip install pre-commit
```

--------------------------------

### Install Pre-release Versions

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/_sources/community/setup.md

Install alpha, beta, or release candidates of the PyData Sphinx theme using pip with the --pre flag.

```console
$ pip install --pre pydata-sphinx-theme
```

--------------------------------

### Install Playwright and Chromium

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/community/topics/galleries.html

Install the Playwright library and the Chromium browser add-on required for generating gallery images locally.

```bash
$ pip install playwright
$ playwright install chromium

```

--------------------------------

### Install pre-commit

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/community/setup.html

Install the pre-commit package using pip. This tool helps maintain code standards by running checks before each commit.

```bash
$ pip install pre-commit

```

--------------------------------

### Install Playwright

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/_sources/community/topics/galleries.md

Installs the playwright library and the Chromium browser add-on, required for generating gallery images locally.

```bash
pip install playwright
playwright install chromium
```

--------------------------------

### Serve Documentation Locally

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/_sources/community/topics/manual-dev.md

Start a local live server to automatically build and serve documentation, opening it in a browser.

```bash
$ stb serve docs --open-browser
```

--------------------------------

### Example Version Switcher Entry

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/user_guide/announcements.html

This is an example of a version switcher entry that the version warning banner relies on. Ensure your version switcher `.json` has exactly one entry with `"preferred": true` and parsable `version` properties.

```json
{
    "name": "stable",
    "version": "9.9.9",
    "url": "https://anything",
    "preferred": true
}

```

--------------------------------

### Install theme with development dependencies

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/community/topics/manual-dev.html

Install the theme locally in editable mode with all development dependencies. This command ensures all necessary packages for development and testing are available.

```bash
$ pip install -e ".[dev]"

```

--------------------------------

### Version Warning Banner Configuration Example

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/_sources/user_guide/announcements.rst

Example JSON structure for the version switcher, which is required for the version warning banner to function correctly. Ensure exactly one entry has `"preferred": true`.

```json
{
    "name": "stable",
    "version": "9.9.9",
    "url": "https://anything",
    "preferred": true
}
```

--------------------------------

### Line Block Example

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/examples/kitchen-sink/blocks.html

Shows a line block, preserving line breaks and indentation. Each line starts with a vertical bar '|'. Continuation lines start with a space.

```rst
This is a normal text paragraph.
This is a line block. It ends with a blank line.
Each new line begins with a vertical bar (“|”).
Line breaks and initial indents are preserved.
Continuation lines are wrapped portions of long lines; they begin with a space in place of the vertical bar.
The left edge of a continuation line need not be aligned with the left edge of the text above it.
This is a second line block.
  

Blank lines are permitted internally, but they must begin with a “|”.
This is a normal text paragraph again.
```

--------------------------------

### Example Fortran Code Block

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/user_guide/web-components.html

Demonstrates a basic Fortran main program. This is an example of a code block within a tabbed interface.

```fortran
PROGRAM main
END PROGRAM main
```

--------------------------------

### GUI Label Example

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/examples/kitchen-sink/generic.html

Illustrates the GUI label role for indicating user actions.

```rst
`this label`
```

--------------------------------

### Install Pre-release Versions

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/community/setup.html

Install alpha, beta, or release candidates of the PyData Sphinx theme using pip with the --pre flag. This is useful for testing or catching regressions before a release.

```bash
pip install --pre pydata-sphinx-theme
```

--------------------------------

### Install development version with pip

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/_sources/user_guide/install.rst

Install the latest development version of the theme directly from its git repository using pip. This is useful for testing upcoming features or reporting bugs.

```console
$ pip install git+https://github.com/pydata/pydata-sphinx-theme.git@main
```

--------------------------------

### Hlist Example

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/examples/kitchen-sink/lists.html

Demonstrates horizontal lists (Hlists) for compact item display.

```rst
* First item
* Second item
* Third item

| 
  * Forth item
  * Fifth item
  * Sixths item

  
---|---
```

```rst
Hlist with images
  * 
|
  * 
  
---|---
```

--------------------------------

### Theme-Agnostic Image (RST)

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/_sources/user_guide/light-dark.rst

Example of an image that works in both light and dark themes, using the 'p-2' class. This example shows RST syntax.

```rst
.. image:: https://source.unsplash.com/200x200/daily?cute+cat
    :class: p-2
```

--------------------------------

### Example Java Code Block

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/user_guide/web-components.html

Demonstrates a basic Java main method. This is an example of a code block within a tabbed interface.

```java
class Main {
    public static void main(String[] args) {
    }
}
```

--------------------------------

### Theme-Agnostic Image (Markdown)

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/_sources/user_guide/light-dark.rst

Example of an image that works in both light and dark themes, using the 'p-2' class. This example shows Markdown syntax.

```md
```{image} https://source.unsplash.com/200x200/daily?cute+cat
:class: p-2
```
```

--------------------------------

### Simple Table Example

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/_sources/examples/kitchen-sink/tables.rst

Illustrates a simple table format for presenting input-output relationships. Suitable for concise data summaries.

```text
=====  =====  ======
   Inputs     Output
------------  ------
  A      B    A or B
=====  =====  ======
False  False  False
True   False  True
False  True   True
True   True   True
=====  =====  ======
=====
```

--------------------------------

### Tabbed Code Examples

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/_sources/user_guide/web-components.rst

Demonstrates how to create tabbed code blocks for different programming languages.

```c++
int main(const int argc, const char **argv) {
    return 0;
}
```

```python
def main():
    return
```

```java
class Main {
    public static void main(String[] args) {
    }
}
```

```julia
function main()
end
```

```fortran
PROGRAM main
END PROGRAM main
```

--------------------------------

### Dropdown Example with Content

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/_sources/user_guide/web-components.rst

A basic dropdown component with content, but no title.

```html
And with no title and some content!
```

--------------------------------

### Example Footnote with Label

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/_sources/examples/kitchen-sink/generic.rst

Demonstrates creating a footnote with a custom label for cross-referencing.

```rst
.. [#label] Footnotes may be numbered, either manually (as in [1]_)
   or automatically using a "#"-prefixed label.  This footnote has a
   label so it can be referred to from multiple places, both as a
   footnote reference ([#label]_)
   and as a hyperlink reference
   (label_).

.. [#] This footnote is numbered automatically and anonymously using a
   label of "#" only.

.. [*] Footnotes may also use symbols, specified with a "*" label.
   Here's a reference to the next footnote: [*]_.

.. [*] This footnote shows the next symbol in the sequence.
```

--------------------------------

### Configure Footer Start, Center, and End Sections

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/user_guide/layout.html

Customize the footer content by defining templates for the 'footer_start', 'footer_center', and 'footer_end' options. Default templates are provided for start and end sections.

```python
html_theme_options = {
  #...
  "footer_start": ["copyright", "sphinx-version"],
  "footer_end": ["theme-version"]
  #...
}
```

--------------------------------

### Glossary Examples

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/examples/kitchen-sink/lists.html

Demonstrates glossary definitions, including multi-paragraph entries.

```rst
Documentation#
    
Provides users with the knowledge they need to use something.
```

```rst
Reading#
    
The process of taking information into ones mind through the use of eyes.
```

```rst
Writing#
    
The process of putting thoughts into a medium for other people to read.
```

```rst
Import Package#
    
A Python module which can contain other modules or recursively, other packages.
An import package is more commonly referred to with the single word “package”, but this guide will use the expanded term when more clarity is needed to prevent confusion with a Distribution Package which is also commonly called a “package”.
```

```rst
Package Index#
    
A repository of distributions with a web interface to automate package discovery and consumption.
```

--------------------------------

### Simple Table Example

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/examples/kitchen-sink/tables.html

Illustrates a simple table with two columns, demonstrating boolean logic operations.

```markdown
Inputs | Output
---|---
A | B | A or B
False | False | False
True | False | True
False | True | True
True | True | True
```

--------------------------------

### Inline Code Example

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/examples/kitchen-sink/generic.html

Demonstrates the use of inline code formatting using single backticks.

```rst
`inline code`
```

--------------------------------

### Giant Table Example

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/examples/kitchen-sink/tables.html

Shows a wide table with multiple columns, demonstrating how content can be laid out horizontally.

```markdown
Header 1 | Header 2 | Header 3 | Header 1 | Header 2 | Header 3 | Header 1 | Header 2 | Header 3 | Header 1 | Header 2 | Header 3
---|---|---|---|---|---|---|---|---|---|---|---
body row 1 | column 2 | column 3 | body row 1 | column 2 | column 3 | body row 1 | column 2 | column 3 | body row 1 | column 2 | column 3
body row 1 | column 2 | column 3 | body row 1 | column 2 | column 3 | body row 1 | column 2 | column 3 | body row 1 | column 2 | column 3
body row 1 | column 2 | column 3 | body row 1 | column 2 | column 3 | body row 1 | column 2 | column 3 | body row 1 | column 2 | column 3
body row 1 | column 2 | column 3 | body row 1 | column 2 | column 3 | body row 1 | column 2 | column 3 | body row 1 | column 2 | column 3
```

--------------------------------

### Executing Python Code with Matplotlib and NumPy (jupyter-sphinx)

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/_sources/examples/execution.rst

This example demonstrates using `jupyter-sphinx` to execute Python code that generates a scatter plot using Matplotlib and NumPy. Ensure `matplotlib` and `numpy` are installed in your environment.

```python
import matplotlib.pyplot as plt
import numpy as np

rng = np.random.default_rng()
data = rng.standard_normal((3, 100))
fig, ax = plt.subplots()
ax.scatter(data[0], data[1], c=data[2], s=3)
```

--------------------------------

### List Table Example

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/examples/kitchen-sink/tables.html

Illustrates a list table with a caption, demonstrating how to structure tabular data using a list-like format.

```markdown
List tables can have captions like this one.# List table | Header 1 | Header 2 | Header 3 long. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam sit amet mauris arcu.
---|---|---|---
Stub Row 1 | Row 1 | Column 2 | Column 3 long. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam sit amet mauris arcu.
Stub Row 2 | Row 2 | Column 2 | Column 3 long. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam sit amet mauris arcu.
Stub Row 3 | Row 3 | Column 2 | Column 3 long. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam sit amet mauris arcu.
```

--------------------------------

### Doctest Block Example

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/_sources/examples/kitchen-sink/blocks.rst

Illustrates a doctest block, representing an interactive Python session for documentation and testing.

```python
>>> print('Python-specific usage examples; begun with ">>>"')
Python-specific usage examples; begun with ">>>"
>>> print("(cut and pasted from interactive Python sessions)")
(cut and pasted from interactive Python sessions)
```

--------------------------------

### Table with Code Snippets

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/examples/kitchen-sink/tables.html

Demonstrates a table where cells contain code snippets, specifically for package installation commands.

```markdown
Version | Installing
---|---
Pradyun’s pip fork and installer | ```
pip install "pip @ git+https://github.com/pradyunsg/pip#20.3.3" "installer @ git+https://github.com/pradyunsg/installer"
```

PyPI | ```
pip install pip installer
```
```

--------------------------------

### Run Development Server with Live Preview

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/_sources/community/setup.md

Combines building documentation and compiling assets with a live development server. Changes in specified directories trigger automatic bundling, regeneration, and Sphinx re-runs, with live preview updates.

```console
# note the -m flag vs. other commands in this guide
$ tox run -m docs-live-server
```

--------------------------------

### Toggle Button Example

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/_sources/user_guide/web-components.rst

An example of a toggle button that hides and reveals content upon clicking.

```html
This will be hidden until a click!
```

--------------------------------

### Option List for Command-Line Options

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/_sources/examples/kitchen-sink/lists.rst

Demonstrates formatting for command-line options, including short and long options, options with arguments, and DOS/VMS-style options.

```rst
-a            command-line option "a"
-b file       options can have arguments
              and long descriptions
--long        options can be long also
--input=file  long options can also have
              arguments

--very-long-option
              The description can also start on the next line.

              The description may contain multiple body elements,
              regardless of where it starts.

-x, -y, -z    Multiple options are an "option group".
-v, --verbose  Commonly-seen: short & long options.
-1 file, --one=file, --two file
              Multiple options with arguments.
/V            DOS/VMS-style options too
```

--------------------------------

### Build Documentation with Tox

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/_sources/community/setup.md

Use this command to build the documentation. It installs dependencies and generates HTML files in the 'docs/_build/html' directory. It only rebuilds updated pages if docs have been previously built.

```console
$ tox run -e docs-dev
```

--------------------------------

### Build documentation with tox

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/community/setup.html

Build the project documentation using tox. This command installs dependencies and generates HTML files in the 'docs/_build/html' directory.

```bash
$ tox run -e docs-dev

```

--------------------------------

### pydata_sphinx_theme.setup

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/_sources/api/pydata_sphinx_theme/index.rst

Sets up the Sphinx application. This function is called by Sphinx during the build process to initialize the theme.

```APIDOC
## pydata_sphinx_theme.setup

### Description
Sets up the Sphinx application. This function is called by Sphinx during the build process to initialize the theme and its configurations.

### Parameters
- **app** (object) - The Sphinx application object.
```

--------------------------------

### Install with Conda

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/_sources/user_guide/install.rst

Install the pydata-sphinx-theme package using conda from the conda-forge channel. This is recommended for users managing environments with conda.

```console
$ conda install pydata-sphinx-theme --channel conda-forge
```

--------------------------------

### Example Version Switcher JSON File

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/_sources/user_guide/version-dropdown.rst

This JSON file defines the versions, URLs, and optional names for the documentation switcher dropdown. It is used to populate the dropdown menu with available documentation versions.

```json
[
    {
        "name": "v2.1 (stable)",
        "version": "2.1",
        "url": "https://mysite.org/en/2.1/"
    },
    {
        "version": "2.1rc1",
        "url": "https://mysite.org/en/2.1rc1/"
    },
    {
        "version": "2.0",
        "url": "https://mysite.org/en/2.0/"
    },
    {
        "version": "1.0",
        "url": "https://mysite.org/en/1.0/"
    }
]
```

--------------------------------

### Example Julia Code Block

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/user_guide/web-components.html

Demonstrates a basic Julia main function. This is an example of a code block within a tabbed interface.

```julia
function main()
end
```

--------------------------------

### Example Python Code Block

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/user_guide/web-components.html

Demonstrates a basic Python main function. This is an example of a code block within a tabbed interface.

```python
def main():
    return
```

--------------------------------

### Example C++ Code Block

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/user_guide/web-components.html

Demonstrates a basic C++ main function. This is an example of a code block within a tabbed interface.

```cpp
int main(const int argc, const char **argv) {
    return 0;
}
```

--------------------------------

### Compile and Bundle Assets

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/_sources/community/topics/assets.md

Run this command to compile the assets and bundle them with the theme. This process places static versions of assets in the theme's static folder.

```console
$ tox -e run compile
```

--------------------------------

### Parsed Literal Block Example

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/examples/kitchen-sink/blocks.html

Demonstrates a parsed literal block, typically rendered in a monospace typeface and useful for code examples with hyperlinks.

```bash
# parsed-literal test
curl -O http://someurl/release-0.1.0.tar-gz
echo "This is an intentionally very long line because I want to make sure that we are handling scrollable code blocks correctly."

```

--------------------------------

### Serve Documentation Locally

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/_sources/community/setup.md

Serve the generated HTML documentation locally using Python's http.server. This is useful for previewing the documentation in a browser.

```console
$ python -m http.server -d docs/_build/html/
```

--------------------------------

### Example of an unexpected warning

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/community/topics/warnings.html

This snippet shows an example of an unexpected warning that might be raised by Sphinx during the build process. It highlights the format of the warning message.

```text
Unexpected warning: C:\hostedtoolcache\windows\Python\3.9.13\x64\lib\site-packages\pandas\core\frame.py:docstring of pandas.core.frame.DataFrame.groupby:42: WARNING: undefined label: 'groupby.transform'


```

--------------------------------

### Build Documentation with Live Reload

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/_sources/community/setup.md

Build the documentation and enable live reloading. This command watches the 'doc' folder for changes and automatically rebuilds the documentation.

```console
$ tox run -e docs-live
```

--------------------------------

### Parsed Literal Block Example

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/_sources/examples/kitchen-sink/blocks.rst

Demonstrates the use of the `parsed-literal` directive, which renders text in a monospaced font and supports hyperlinks. Useful for code examples.

```text
# parsed-literal test
curl -O http://someurl/release-0.1.0.tar-gz
echo "This is an intentionally very long line because I want to make sure that we are handling scrollable code blocks correctly."
```

--------------------------------

### Build Documentation Manually

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/_sources/community/topics/manual-dev.md

Manually build the project's documentation using the sphinx-build command.

```bash
$ sphinx-build docs docs/_build/html
```

--------------------------------

### Run development server with tox

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/community/setup.html

Run a development server that combines documentation builds and asset compilation with live reloading. Changes in specified source directories will trigger automatic updates.

```bash
# note the -m flag vs. other commands in this guide
$ tox run -m docs-live-server

```

--------------------------------

### Example Unexpected Warning

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/_sources/community/topics/warnings.md

An example of an unexpected warning message that might be raised by Sphinx during a build. This format is used to identify and add new warnings to the expected list.

```console
Unexpected warning: C:\hostedtoolcache\windows\Python\3.9.13\x64\lib\site-packages\pandas\core\frame.py:docstring of pandas.core.frame.DataFrame.groupby:42: WARNING: undefined label: 'groupby.transform'
```

--------------------------------

### IPyWidget Tab Setup

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/examples/pydata.html

Initializes an IPyWidget Tab and creates HTML and Output widgets for displaying content. This is part of setting up interactive elements.

```python
import ipywidgets as widgets
import numpy as np
import pandas as pd

from IPython.display import display


tab = widgets.Tab()

descr_str = "Hello"

title = widgets.HTML(descr_str)

# create output widgets
widget_images = widgets.Output()
widget_annotations = widgets.Output()
```

--------------------------------

### Prepare Logo Configuration

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/_modules/pydata_sphinx_theme.html

Prepares the 'logo' configuration dictionary, merging 'logo' and 'theme_logo_link' options. It also validates the type of the logo configuration.

```python
theme_logo = theme_options.get("logo")
if not theme_logo:
    theme_logo = {}
if not isinstance(theme_logo, dict):
    raise ValueError(f"Incorrect logo config type: {type(theme_logo)}")
theme_logo_link = theme_options.get("theme_logo_link")
if theme_logo_link:
    theme_logo["link"] = theme_logo_link
theme_options["logo"] = theme_logo
```

--------------------------------

### Install and Update Dependencies

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/community/topics/dependencies-js.html

Run this command to re-generate the package-lock.json file after editing package.json. It ensures a frozen dependency chain for the theme.

```bash
stb npm install --include=dev

```

--------------------------------

### Add development version to Conda environment

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/_sources/user_guide/install.rst

Include the development version of the theme in a conda environment YAML file using a pip install directive. This ensures the development version is installed when the environment is created.

```yaml
- pip:
  - git+https://github.com/pydata/pydata-sphinx-theme.git@main
```

--------------------------------

### Equivalent Python Configuration

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/community/topics/page-metadata.html

This Python dictionary structure in `conf.py` shows how the page-level metadata maps to the theme's configuration options.

```python
html_theme_options = {
   "sidebar_secondary": {"remove": "true"}
}

```

--------------------------------

### _get_styles

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/api/pydata_sphinx_theme/pygments/index.html

Get styles out of a formatter, where everything has the correct prefix.

```APIDOC
## _get_styles

### Description
Get styles out of a formatter, where everything has the correct prefix.

### Parameters
#### Path Parameters
- **formatter** (_pygments.formatters.HtmlFormatter_) - Description not available
- **prefix** (_str_) - Description not available

### Return Type
None
```

--------------------------------

### Dropdown Example with Title

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/_sources/user_guide/web-components.rst

A dropdown component that includes a title and content.

```html
And some content!
```

--------------------------------

### Download Link Directive

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/_sources/examples/kitchen-sink/generic.rst

Demonstrates creating a downloadable link with a long description that should wrap.

```rst
:download:`This long long long long long long long long long long long long long long long download link should wrap white-spaces <https://source.unsplash.com/200x200/daily?cute+puppy>`
```

--------------------------------

### Configure Analytics Options

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/user_guide/analytics.html

Set up the general analytics configuration by passing a dictionary to the 'analytics' option in html_theme_options. This dictionary will hold provider-specific settings.

```python
html_theme_options = {
    # See below for options for each service
    "analytics": analytics_options,
}

```

--------------------------------

### _get_matching_sidebar_items

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/api/pydata_sphinx_theme/utils/index.html

Get the matching sidebar templates to render for the given pagename.

```APIDOC
## _get_matching_sidebar_items(pagename, sidebars)

### Description
Get the matching sidebar templates to render for the given pagename.

### Parameters
#### Path Parameters
- **pagename** (string) - Required - The name of the current page.
- **sidebars** (list) - Required - A list of sidebar configurations.

### Returns
- list - A list of matching sidebar items.
```

--------------------------------

### Main JavaScript Entry Point

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/community/structure.html

The main JavaScript file that provides additional Bootstrap features and custom navigation behavior.

```javascript
src/pydata_sphinx_theme/assets/scripts/pydata-sphinx-theme.js
```

--------------------------------

### Configure Theme Options for Localization

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/_sources/user_guide/i18n.rst

Set up Sphinx and theme options in conf.py to enable translation of configurable strings. This involves importing necessary modules and defining the text domain.

```python
import os.path
from sphinx.locale import get_translation

catalog = "messages"
_ = get_translation(catalog)

html_theme_options = {
    "search_bar_text": _("Search the docs..."),

    # You only need to translate the following if you use these features.
    "icon_links_label": _("Quick Links"),
    "icon_links": [
        {
            "name": _("GitHub"),
            "url": "https://github.com/<your-org>/<your-repo>",
            "icon": "fab fa-github-square",
        },
    ],
    "external_links": [
        {
            "name": _("link-one-name"),
            "url": "https://<link-one>",
        },
    ],
}

def setup(app):
   locale_dir = os.path.join(os.path.abspath(os.path.dirname(__file__), "locale")

   app.add_message_catalog(catalog, locale_dir)
```

--------------------------------

### Icon Link Shortcuts

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/_sources/user_guide/header-links.rst

Use shortcuts for commonly used services like GitHub, GitLab, Bitbucket, and Twitter to simplify configuration.

```python
html_theme_options = {
    ...
    "github_url": "https://github.com/<your-org>/<your-repo>",
    "gitlab_url": "https://gitlab.com/<your-org>/<your-repo>",
    "bitbucket_url": "https://bitbucket.org/<your-org>/<your-repo>",
    "twitter_url": "https://twitter.com/<your-handle>",
    ...
}
```

--------------------------------

### Localize Theme with Variables and Markup

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/_sources/community/topics/i18n.rst

Demonstrates how to handle localizable strings that include variables and markup using the Jinja `trans` block.

```jinja
{% trans language=language %}
Welcome to the {{ language }} version of the site
{% endtrans %}
```

--------------------------------

### Enumerated List Example

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/examples/kitchen-sink/lists.html

Demonstrates nested enumerated lists with different numbering styles.

```rst
1. Arabic numerals.
  1. lower alpha)
    1. (lower roman)
      1. upper alpha.
        1. upper roman)
```

```rst
2. Lists that don’t start at 1:
    3. Three
    4. Four
    3. C
    4. D
    3. iii
    4. iv
```

```rst
3. List items may also be auto-enumerated.
```

--------------------------------

### Code Block with Line Numbers

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/examples/kitchen-sink/generic.html

A standard code block example with line numbers.

```code
 1print("one")
 2print("two")
 3print("three")
 4print("four")
 5print("five")
 6print("six")
 7print("seven")
 8print("eight")
 9print("nine")
10print("ten")
11print("eleven")
12print("twelve")
13print("thirteen")
14print("fourteen")

```

--------------------------------

### Activate pre-commit Hooks

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/_sources/community/setup.md

Install the Git hooks for pre-commit in the repository to ensure code quality checks are run automatically on commit.

```console
$ pre-commit install
```

--------------------------------

### Dropdown Example with Title and Icon

Source: https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/_sources/user_guide/web-components.rst

A dropdown component featuring a title, an icon, and content.

```html
And some content and an icon!
```
Tokens:
Raw