Skip to content

Commit 683c9aa

Browse files
backwardspybackwardspy
committed
docs: document package with pdoc
1 parent 900189a commit 683c9aa

File tree

12 files changed

+431
-211
lines changed

12 files changed

+431
-211
lines changed

‎.github/workflows/gh-pages.yaml‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,8 +19,10 @@ jobs:
1919
with:
2020
node-version: "latest"
2121
- run: "pip install catppuccin[pygments,gh-pages]"
22+
- run: "mkdir -p gh-pages/docs/assets/ && cp assets/pepperjack.webp gh-pages/docs/assets/"
23+
- 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"
2224
- run: "scripts/build-gh-pages"
23-
- run: "npx lightningcss-cli --minify ./gh-pages/pygments/*.css --output-dir ./gh-pages/pygments/"
25+
- run: "npx lightningcss-cli --minify gh-pages/pygments/*.css --output-dir gh-pages/pygments/"
2426
- uses: "peaceiris/actions-gh-pages@v4"
2527
with:
2628
enable_jekyll: false

‎README.md‎

Lines changed: 19 additions & 166 deletions
Original file line numberDiff line numberDiff line change
@@ -15,109 +15,15 @@
1515

1616
Install with `pip` or your preferred dependency management tool.
1717

18-
```bash
19-
pip install catppuccin
20-
```
21-
22-
## Usage
23-
24-
Get access to the palette with the `catppuccin.PALETTE` constant:
25-
26-
```python
27-
from catppuccin import PALETTE
28-
29-
PALETTE.latte.colors.mauve.hex
30-
# '#8839ef'
31-
PALETTE.mocha.colors.teal.rgb
32-
# RGB(r=148, g=226, b=213)
33-
```
34-
35-
The `Palette` data structure matches [the palette JSON](https://github.com/catppuccin/palette/blob/main/palette.json).
36-
37-
### Iteration
38-
39-
Both `Palette` and `FlavorColors` can be iterated to yield flavors and colors respectively:
40-
41-
```python
42-
for flavor in PALETTE:
43-
print(flavor.name)
44-
45-
# Latte
46-
# Frappé
47-
# Macchiato
48-
# Mocha
49-
50-
for color in PALETTE.latte.colors:
51-
print(f"{color.name}: {color.hex}")
52-
53-
# Rosewater: #f2d5cf
54-
# Flamingo: #eebebe
55-
# Pink: #f4b8e4
56-
# ...
57-
# Base: #303446
58-
# Mantle: #292c3c
59-
# Crust: #232634
60-
```
61-
62-
### dataclasses
63-
64-
`Palette`, `Flavor`, `Color` et cetera are all [`dataclasses`](https://docs.python.org/3/library/dataclasses.html),
65-
so you can also inspect and iterate their fields using methods from the dataclass module.
66-
67-
For example, to list all color names and their hex codes:
68-
69-
```python
70-
from dataclasses import fields
71-
from catppuccin import PALETTE
72-
73-
flavor = PALETTE.frappe
74-
for field in fields(flavor.colors):
75-
color = getattr(flavor.colors, field.name)
76-
print(f"{field.name}: {color.hex}")
77-
78-
# rosewater: #f2d5cf
79-
# flamingo: #eebebe
80-
# pink: #f4b8e4
81-
# ...
82-
# base: #303446
83-
# mantle: #292c3c
84-
# crust: #232634
8518
```
86-
87-
## Pygments Styles
88-
89-
This package provides a Pygments style for each of the four Catppuccin flavors.
90-
91-
Install Catppuccin with the `pygments` feature to include the relevant dependencies:
92-
93-
```bash
94-
pip install catppuccin[pygments]
95-
```
96-
97-
The styles are registered as importlib entrypoints, which allows Pygments to
98-
find them by name:
99-
100-
```python
101-
from pygments.styles import get_style_by_name
102-
103-
get_style_by_name("catppuccin-frappe")
104-
# catppuccin.extras.pygments.FrappeStyle
19+
pip install catppuccin
10520
```
10621

107-
The following style names are available:
108-
109-
- `catppuccin-latte`
110-
- `catppuccin-frappe`
111-
- `catppuccin-macchiato`
112-
- `catppuccin-mocha`
22+
## Documentation
11323

114-
They can also be accessed by directly importing them:
24+
For an API reference and usage examples, [see our online documentation](https://python.catppuccin.com/docs).
11525

116-
```python
117-
from catppuccin.extras.pygments import MacchiatoStyle
118-
```
119-
120-
### IPython
26+
## IPython Theme
12127

12228
A minimal configuration:
12329

@@ -131,65 +37,12 @@ and ensuring `catppuccin[pygments]` is installed in the same environment will
13137
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)
13238
for an example of a more complete configuration.
13339

134-
## Matplotlib
135-
136-
The library tries to register styles and colormaps if `matplotlib` is installed.
137-
See the examples below for some use cases:
138-
139-
1. Load a style, using `mpl.style.use`
140-
141-
```python
142-
import catppuccin
143-
import matplotlib as mpl
144-
import matplotlib.pyplot as plt
145-
146-
mpl.style.use(catppuccin.PALETTE.mocha.identifier)
147-
plt.plot([0,1,2,3], [1,2,3,4])
148-
plt.show()
149-
```
150-
151-
1. Mix it with different stylesheets!
152-
153-
```python
154-
import catppuccin
155-
import matplotlib as mpl
156-
import matplotlib.pyplot as plt
157-
158-
mpl.style.use(["ggplot", catppuccin.PALETTE.mocha.identifier])
159-
plt.plot([0,1,2,3], [1,2,3,4])
160-
plt.show()
161-
```
162-
163-
1. Load individual colors
40+
Available IPython themes:
16441

165-
```python
166-
import matplotlib.pyplot as plt
167-
import catppuccin
168-
from catppuccin.extras.matplotlib import load_color
169-
170-
color = load_color(catppuccin.PALETTE.latte.identifier, "peach")
171-
plt.plot([0,1,2,3], [1,2,3,4], color=color)
172-
plt.show()
173-
```
174-
175-
1. Define custom colormaps
176-
177-
```python
178-
import matplotlib.pyplot as plt
179-
import numpy as np
180-
import catppuccin
181-
from catppuccin.extras.matplotlib import get_colormap_from_list
182-
183-
cmap = get_colormap_from_list(
184-
catppuccin.PALETTE.frappe.identifier,
185-
["red", "peach", "yellow", "green"],
186-
)
187-
rng = np.random.default_rng()
188-
data = rng.integers(2, size=(30, 30))
189-
190-
plt.imshow(data, cmap=cmap)
191-
plt.show()
192-
```
42+
- `catppuccin-latte`
43+
- `catppuccin-frappe`
44+
- `catppuccin-macchiato`
45+
- `catppuccin-mocha`
19346

19447
## Contribution
19548

@@ -205,7 +58,7 @@ instructions](https://docs.astral.sh/uv/getting-started/installation/).
20558

20659
Install the project's dependencies including extras:
20760

208-
```bash
61+
```
20962
uv sync --all-extras
21063
```
21164

@@ -215,7 +68,7 @@ uv sync --all-extras
21568

21669
To update after downloading a new palette JSON file:
21770

218-
```console
71+
```
21972
uv run build.py
22073
```
22174

@@ -232,8 +85,8 @@ Tests are run with [`pytest`](https://docs.pytest.org/en/stable/).
23285

23386
To run tests and display coverage:
23487

235-
```console
236-
$ pytest --cov catppuccin
88+
```
89+
pytest --cov catppuccin
23790
```
23891

23992
##### Type Checking
@@ -242,8 +95,8 @@ Type checking is performed by [`mypy`](https://www.mypy-lang.org/).
24295

24396
To run type checks:
24497

245-
```console
246-
$ mypy .
98+
```
99+
mypy .
247100
```
248101

249102
##### Lints and Formatting
@@ -252,14 +105,14 @@ Code linting and formatting is done by [`ruff`](https://docs.astral.sh/ruff/).
252105

253106
To lint the code:
254107

255-
```console
256-
$ ruff check
108+
```
109+
ruff check
257110
```
258111

259112
To format the code:
260113

261-
```console
262-
$ ruff format
114+
```
115+
ruff format
263116
```
264117

265118
## 💝 Thanks to

‎assets/pepperjack.webp‎

23.8 KB
Loading

‎catppuccin/__init__.py‎

Lines changed: 86 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,94 @@
1-
"""🐍 Soothing pastel theme for Python."""
1+
"""🐍 Soothing pastel theme for Python.
2+
3+
## Basic Usage
4+
5+
Get access to the palette with the `catppuccin.PALETTE` constant:
6+
7+
```python
8+
from catppuccin import PALETTE
9+
10+
PALETTE.latte.colors.mauve.hex
11+
# '#8839ef'
12+
PALETTE.mocha.colors.teal.rgb
13+
# RGB(r=148, g=226, b=213)
14+
```
15+
16+
The `Palette` data structure matches [the palette
17+
JSON](https://github.com/catppuccin/palette/blob/main/palette.json).
18+
19+
## Iteration
20+
21+
Both `Palette` and `FlavorColors` can be iterated to yield flavors and colors
22+
respectively:
23+
24+
```python
25+
for flavor in PALETTE:
26+
print(flavor.name)
27+
28+
# Latte
29+
# Frappé
30+
# Macchiato
31+
# Mocha
32+
33+
for color in PALETTE.latte.colors:
34+
print(f"{color.name}: {color.hex}")
35+
36+
# Rosewater: #f2d5cf
37+
# Flamingo: #eebebe
38+
# Pink: #f4b8e4
39+
# ...
40+
# Base: #303446
41+
# Mantle: #292c3c
42+
# Crust: #232634
43+
```
44+
45+
## Dataclasses
46+
47+
`Palette`, `Flavor`, `Color` et cetera are all
48+
[`dataclasses`](https://docs.python.org/3/library/dataclasses.html),
49+
so you can also inspect and iterate their fields using methods from the
50+
dataclass module.
51+
52+
For example, to list all color names and their hex codes:
53+
54+
```python
55+
from dataclasses import fields
56+
from catppuccin import PALETTE
57+
58+
flavor = PALETTE.frappe
59+
for field in fields(flavor.colors):
60+
color = getattr(flavor.colors, field.name)
61+
print(f"{field.name}: {color.hex}")
62+
63+
# rosewater: #f2d5cf
64+
# flamingo: #eebebe
65+
# pink: #f4b8e4
66+
# ...
67+
# base: #303446
68+
# mantle: #292c3c
69+
# crust: #232634
70+
```
71+
72+
## Types
73+
74+
This package is fully type annotated with data structures located in [the models
75+
module](./catppuccin/models.html).
76+
77+
## Integrations
78+
79+
This package includes optional support for several libraries. Click a link below
80+
to see the documentation for that integration.
81+
82+
- [matplotlib](./catppuccin/extras/matplotlib.html)
83+
- [pygments](./catppuccin/extras/pygments.html)
84+
- [rich](./catppuccin/extras/rich_ctp.html)
85+
86+
"""
287

388
import importlib.util
489

590
from catppuccin.palette import PALETTE
691

7-
__all__ = ["PALETTE"]
8-
992
# Attempt to register styles and colormaps if matplotlib is available
1093
if importlib.util.find_spec("matplotlib") is not None:
1194
from catppuccin.extras.matplotlib import _register_colormap_list, _register_styles

0 commit comments

Comments
 (0)