docs: document package with pdoc

.github/workflows/gh-pages.yaml

@@ -19,8 +19,10 @@ jobs:
         with:
           node-version: "latest"
       - run: "pip install catppuccin[pygments,gh-pages]"
+      - run: "mkdir -p gh-pages/docs/assets/ && cp assets/pepperjack.webp gh-pages/docs/assets/"
+      - run: "uv run pdoc catppuccin --no-include-undocumented --favicon https://catppuccin.com/favicon.png --logo https://python.catppuccin.com/docs/assets/pepperjack.webp --logo-link / --template-directory pdoc --output-directory gh-pages/docs"
       - run: "scripts/build-gh-pages"
-      - run: "npx lightningcss-cli --minify ./gh-pages/pygments/*.css --output-dir ./gh-pages/pygments/"
+      - run: "npx lightningcss-cli --minify gh-pages/pygments/*.css --output-dir gh-pages/pygments/"
       - uses: "peaceiris/actions-gh-pages@v4"
         with:
           enable_jekyll: false

README.md

@@ -15,109 +15,15 @@
 
 Install with `pip` or your preferred dependency management tool.
 
-```bash
-pip install catppuccin
-```
-
-## Usage
-
-Get access to the palette with the `catppuccin.PALETTE` constant:
-
-```python
-from catppuccin import PALETTE
-
-PALETTE.latte.colors.mauve.hex
-# '#8839ef'
-PALETTE.mocha.colors.teal.rgb
-# RGB(r=148, g=226, b=213)
-```
-
-The `Palette` data structure matches [the palette JSON](https://github.com/catppuccin/palette/blob/main/palette.json).
-
-### Iteration
-
-Both `Palette` and `FlavorColors` can be iterated to yield flavors and colors respectively:
-
-```python
-for flavor in PALETTE:
-    print(flavor.name)
-
-# Latte
-# Frappé
-# Macchiato
-# Mocha
-
-for color in PALETTE.latte.colors:
-    print(f"{color.name}: {color.hex}")
-
-# Rosewater: #f2d5cf
-# Flamingo: #eebebe
-# Pink: #f4b8e4
-# ...
-# Base: #303446
-# Mantle: #292c3c
-# Crust: #232634
-```
-
-### dataclasses
-
-`Palette`, `Flavor`, `Color` et cetera are all [`dataclasses`](https://docs.python.org/3/library/dataclasses.html),
-so you can also inspect and iterate their fields using methods from the dataclass module.
-
-For example, to list all color names and their hex codes:
-
-```python
-from dataclasses import fields
-from catppuccin import PALETTE
-
-flavor = PALETTE.frappe
-for field in fields(flavor.colors):
-    color = getattr(flavor.colors, field.name)
-    print(f"{field.name}: {color.hex}")
-
-# rosewater: #f2d5cf
-# flamingo: #eebebe
-# pink: #f4b8e4
-# ...
-# base: #303446
-# mantle: #292c3c
-# crust: #232634
 ```
-
-## Pygments Styles
-
-This package provides a Pygments style for each of the four Catppuccin flavors.
-
-Install Catppuccin with the `pygments` feature to include the relevant dependencies:
-
-```bash
-pip install catppuccin[pygments]
-```
-
-The styles are registered as importlib entrypoints, which allows Pygments to
-find them by name:
-
-```python
-from pygments.styles import get_style_by_name
-
-get_style_by_name("catppuccin-frappe")
-# catppuccin.extras.pygments.FrappeStyle
+pip install catppuccin
 ```
 
-The following style names are available:
-
-- `catppuccin-latte`
-- `catppuccin-frappe`
-- `catppuccin-macchiato`
-- `catppuccin-mocha`
+## Documentation
 
-They can also be accessed by directly importing them:
+For an API reference and usage examples, [see our online documentation](https://python.catppuccin.com/docs).
 
-```python
-from catppuccin.extras.pygments import MacchiatoStyle
-```
-
-### IPython
+## IPython Theme
 
 A minimal configuration:
 
@@ -131,65 +37,12 @@ and ensuring `catppuccin[pygments]` is installed in the same environment will
 give you Catppuccin Mocha syntax highlighting in the REPL. See [here](https://github.com/backwardspy/dots/blob/f6991570d6691212e27e266517656192f910ccbf/dot_config/ipython/profile_default/ipython_config.py)
 for an example of a more complete configuration.
 
-## Matplotlib
-
-The library tries to register styles and colormaps if `matplotlib` is installed.
-See the examples below for some use cases:
-
-1. Load a style, using `mpl.style.use`
-
-   ```python
-   import catppuccin
-   import matplotlib as mpl
-   import matplotlib.pyplot as plt
-
-   mpl.style.use(catppuccin.PALETTE.mocha.identifier)
-   plt.plot([0,1,2,3], [1,2,3,4])
-   plt.show()
-   ```
-
-1. Mix it with different stylesheets!
-
-   ```python
-   import catppuccin
-   import matplotlib as mpl
-   import matplotlib.pyplot as plt
-
-   mpl.style.use(["ggplot", catppuccin.PALETTE.mocha.identifier])
-   plt.plot([0,1,2,3], [1,2,3,4])
-   plt.show()
-   ```
-
-1. Load individual colors
+Available IPython themes:
 
-   ```python
-   import matplotlib.pyplot as plt
-   import catppuccin
-   from catppuccin.extras.matplotlib import load_color
-
-   color = load_color(catppuccin.PALETTE.latte.identifier, "peach")
-   plt.plot([0,1,2,3], [1,2,3,4], color=color)
-   plt.show()
-   ```
-
-1. Define custom colormaps
-
-   ```python
-   import matplotlib.pyplot as plt
-   import numpy as np
-   import catppuccin
-   from catppuccin.extras.matplotlib import get_colormap_from_list
-
-   cmap = get_colormap_from_list(
-       catppuccin.PALETTE.frappe.identifier,
-       ["red", "peach", "yellow", "green"],
-   )
-   rng = np.random.default_rng()
-   data = rng.integers(2, size=(30, 30))
-
-   plt.imshow(data, cmap=cmap)
-   plt.show()
-   ```
+- `catppuccin-latte`
+- `catppuccin-frappe`
+- `catppuccin-macchiato`
+- `catppuccin-mocha`
 
 ## Contribution
 
@@ -205,7 +58,7 @@ instructions](https://docs.astral.sh/uv/getting-started/installation/).
 
 Install the project's dependencies including extras:
 
-```bash
+```
 uv sync --all-extras
 ```
 
@@ -215,7 +68,7 @@ uv sync --all-extras
 
 To update after downloading a new palette JSON file:
 
-```console
+```
 uv run build.py
 ```
 
@@ -232,8 +85,8 @@ Tests are run with [`pytest`](https://docs.pytest.org/en/stable/).
 
 To run tests and display coverage:
 
-```console
-$ pytest --cov catppuccin
+```
+pytest --cov catppuccin
 ```
 
 ##### Type Checking
@@ -242,8 +95,8 @@ Type checking is performed by [`mypy`](https://www.mypy-lang.org/).
 
 To run type checks:
 
-```console
-$ mypy .
+```
+mypy .
 ```
 
 ##### Lints and Formatting
@@ -252,14 +105,14 @@ Code linting and formatting is done by [`ruff`](https://docs.astral.sh/ruff/).
 
 To lint the code:
 
-```console
-$ ruff check
+```
+ruff check
 ```
 
 To format the code:
 
-```console
-$ ruff format
+```
+ruff format
 ```
 
 ## 💝 Thanks to

catppuccin/__init__.py

@@ -1,10 +1,93 @@
-"""🐍 Soothing pastel theme for Python."""
+"""🐍 Soothing pastel theme for Python.
 
-import importlib.util
+## Basic Usage
+
+Get access to the palette with the `catppuccin.PALETTE` constant:
+
+```python
+from catppuccin import PALETTE
+
+PALETTE.latte.colors.mauve.hex
+# '#8839ef'
+PALETTE.mocha.colors.teal.rgb
+# RGB(r=148, g=226, b=213)
+```
+
+The `Palette` data structure matches [the palette
+JSON](https://github.com/catppuccin/palette/blob/main/palette.json).
+
+## Iteration
+
+Both `Palette` and `FlavorColors` can be iterated to yield flavors and colors
+respectively:
+
+```python
+for flavor in PALETTE:
+    print(flavor.name)
+
+# Latte
+# Frappé
+# Macchiato
+# Mocha
+
+for color in PALETTE.latte.colors:
+    print(f"{color.name}: {color.hex}")
+
+# Rosewater: #f2d5cf
+# Flamingo: #eebebe
+# Pink: #f4b8e4
+# ...
+# Base: #303446
+# Mantle: #292c3c
+# Crust: #232634
+```
+
+## Dataclasses
 
-from catppuccin.palette import PALETTE
+`Palette`, `Flavor`, `Color` et cetera are all
+[`dataclasses`](https://docs.python.org/3/library/dataclasses.html),
+so you can also inspect and iterate their fields using methods from the
+dataclass module.
+
+For example, to list all color names and their hex codes:
+
+```python
+from dataclasses import fields
+from catppuccin import PALETTE
+
+flavor = PALETTE.frappe
+for field in fields(flavor.colors):
+    color = getattr(flavor.colors, field.name)
+    print(f"{field.name}: {color.hex}")
+
+# rosewater: #f2d5cf
+# flamingo: #eebebe
+# pink: #f4b8e4
+# ...
+# base: #303446
+# mantle: #292c3c
+# crust: #232634
+```
+
+## Types
+
+This package is fully type annotated with data structures located in [the models
+module](./catppuccin/models.html).
+
+## Integrations
+
+This package includes optional support for several libraries. Click a link below
+to see the documentation for that integration.
+
+- [matplotlib](./catppuccin/extras/matplotlib.html)
+- [pygments](./catppuccin/extras/pygments.html)
+- [rich](./catppuccin/extras/rich_ctp.html)
+
+"""
+
+import importlib.util
 
-__all__ = ["PALETTE"]
+from catppuccin.palette import PALETTE as PALETTE
 
 # Attempt to register styles and colormaps if matplotlib is available
 if importlib.util.find_spec("matplotlib") is not None: