Metadata-Version: 2.1
Name: jupyterhub-sphinx-theme
Version: 0.1.0
Summary: JupyterHub's Documentation Theme.
Author-Email: JupyterHub <hello@jupyter.org>
License: BSD 3-Clause License
        
        Copyright (c) 2020, Chris Holdgraf
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice, this
           list of conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions and the following disclaimer in the documentation
           and/or other materials provided with the distribution.
        
        3. Neither the name of the copyright holder nor the names of its
           contributors may be used to endorse or promote products derived from
           this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Classifier: Framework :: Sphinx
Classifier: Framework :: Sphinx :: Theme
Classifier: License :: OSI Approved :: MIT License
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Documentation
Project-URL: Organization, https://jupyter.org
Requires-Python: >=3.8
Requires-Dist: myst-parser
Requires-Dist: pydata-sphinx-theme>=0.14.0
Requires-Dist: sphinx-copybutton
Requires-Dist: sphinxext-opengraph
Requires-Dist: sphinx-theme-builder[cli]; extra == "dev"
Provides-Extra: dev
Description-Content-Type: text/markdown

# The JupyterHub Documentation Theme

A lightweight theme built on the PyData Sphinx Theme, for use by the JupyterHub community.
It makes minimal changes to the `pydata-sphinx-theme` in order to standardize styles and a top-bar that can be shared across all JupyterHub documentation.

## Defaults this theme sets

This theme sets a few default values to standardize the look and feel across JupyterHub documentation.

```{note}
If there are other standard features/customizations that would be helpful across the JupyterHub team documentation, we can probably add it here so please open an issue to discuss.
```

Here is a brief summary:

### Style

- Sets the primary color to a slightly-darkened "Jupyter orange"
- Removes primary color from headers and makes them bold to be noticeable
- Aligns the header links to the left

### Logo and branding

- Adds a light/dark mode JupyterHub logo
- Adds a favicon
- Adds icon links for our Discourse, Team Compass, and Jupyter.org

### Extensions

- [`sphinx-copybutton`](https://sphinx-copybutton.readthedocs.io/) for copy buttons in our code cells.
- [`sphinxext-opengraph`](https://sphinxext-opengraph.readthedocs.io/en/latest/) for OpenGraph protocol metadata. `site_url` will automatically be detected via `ReadTheDocs` or `GitHub Actions` environment variables in CI/CD.

## How to use this theme

Follow these steps:

1. Add this theme to the `pip` install requirements of the repo.
   For now, point it to the `main` branch like so:

   ```
   # in requirements.txt
   git+https://github.com/jupyterhub/jupyterhub-sphinx-theme
   ```

   or to install locally

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

2. Configure the Sphinx docs to use the theme by editing `conf.py`

   ```{code-block} python
   :caption: conf.py

   html_theme = "jupyterhub_sphinx_theme"
   ```

3. Add it to your theme's extensions:

   ```{code-block} python
   :caption: conf.py

   extensions = [
      "jupyterhub_sphinx_theme"
   ]
   ```

## Make customizations on top of these defaults

You can make customizations on top of the defaults in this theme.
See [the PyData theme documentation](https://pydata-sphinx-theme.readthedocs.io/) for guidance on what is possible.

In general, this theme only sets defaults, and you can override whatever you like.

## Developer documentation

### Theme build system

This theme uses the [`sphinx-theme-builder` tool](https://github.com/pradyunsg/sphinx-theme-builder), which is a helper tool for automatically compiling Sphinx theme assets.
This will download a local copy of NodeJS and build the theme's assets with the environment specified in `package.json`.

### Theme structure

This theme follows the [`sphinx-theme-builder` filesystem layout](https://sphinx-theme-builder.readthedocs.io/en/latest/reference/filesystem-layout/).

### Build the theme locally

You can build the documentation for this theme to preview it.
The easiest way to build the documentation in this repository is to use [the `nox` automation tool](https://nox.thea.codes/), a tool for quickly building environments and running commands within them.
This ensures that your environment has all the dependencies needed to build the documentation.

To do so, follow these steps:

1. Install `nox`

   ```console
   $ pip install nox
   ```

2. Build the documentation:

   ```console
   $ nox -s docs
   ```

This should create a local environment in a `.nox` folder, build the documentation (as specified in the `noxfile.py` configuration), and the output will be in `docs/_build/html`.

To build live documentation that updates when you update local files, run the following command:

```console
$ nox -s docs-live
```

## Make a release

Follow the instructions in [RELEASE.md](https://github.com/jupyterhub/jupyterhub-sphinx-theme/blob/main/RELEASE.md)
