Skip to content

Commit f7ea70a

Browse files
alexanderthclarkclaude
alexanderthclark
and
claude
committed
Add Jupyter Book conversion of Chapters 1 and 2
- Set up Jupyter Book structure with _config.yml and _toc.yml - Convert Chapter 1 "The Object-oriented Interface" from LaTeX to Markdown - Convert Chapter 2 "Axes Appearance, Ticks, and Grids" from LaTeX to Markdown - Add all preface sections (technical notes, why matplotlib, etc.) - Convert PDF figures to PNG format for web display - Add custom CSS styling and Tony Hawk favicon - Create proper .gitignore to exclude build artifacts - Add CLAUDE.md for AI assistance guidance - Include Blake Urizen plate 8 image for title page 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
1 parent bb2f60e commit f7ea70a

58 files changed

Lines changed: 1109 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.gitignore‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# Python
2+
__pycache__/
3+
*.py[cod]
4+
*$py.class
5+
*.so
6+
.Python
7+
env/
8+
venv/
9+
.env
10+
11+
# Jupyter
12+
.ipynb_checkpoints/
13+
*.ipynb_checkpoints
14+
15+
# Jupyter Book build files
16+
jupyterbook/_build/
17+
jupyterbook/.jupyter_cache/
18+
19+
# LaTeX
20+
*.aux
21+
*.log
22+
*.out
23+
*.toc
24+
*.fls
25+
*.fdb_latexmk
26+
*.synctex.gz
27+
*.bbl
28+
*.blg
29+
30+
# OS files
31+
.DS_Store
32+
Thumbs.db
33+
34+
# IDE
35+
.vscode/
36+
.idea/
37+
*.swp
38+
*.swo
39+
40+
# Other
41+
*.bak
42+
*.tmp

‎CLAUDE.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Project Overview
6+
7+
This is the repository for "Matplotlib for Storytellers", a Python data visualization book that teaches frustrated matplotlib users how to craft good data visuals. The project contains:
8+
9+
- LaTeX source files for the book (main.tex and supporting files in tex/)
10+
- Python scripts generating matplotlib figures (python/)
11+
- Generated figure outputs (figures/)
12+
- Demo Jupyter notebooks (Demos/)
13+
- Data files for examples (Data/)
14+
15+
## Key Commands
16+
17+
### Building the Book
18+
```bash
19+
# Compile the LaTeX book
20+
pdflatex main.tex
21+
# Run multiple times if needed for references/TOC
22+
```
23+
24+
### Running Python Scripts
25+
```bash
26+
# Generate figures - scripts save to figures/ directory
27+
cd python/
28+
python <script-name>.py
29+
```
30+
31+
### Common Dependencies
32+
The project uses these Python libraries:
33+
- matplotlib
34+
- numpy
35+
- pandas
36+
- scipy
37+
- scikit-learn (sklearn)
38+
- ternary (optional, for ternary plots)
39+
40+
## Architecture Notes
41+
42+
1. **Figure Generation**: Python scripts in `python/` generate PDF figures saved to `figures/` subdirectories (mathplots/, poetryplots/, proseplots/, specialplots/)
43+
44+
2. **Book Structure**: The main LaTeX file `main.tex` includes chapters from `tex/` subdirectories:
45+
- prose/ - Core matplotlib concepts
46+
- poetry/ - Advanced visualizations
47+
- math/ - Mathematical interlude
48+
- special/ - Special topics (MDS, stats, ternary plots)
49+
50+
3. **Style Files**:
51+
- Custom matplotlib styles in `stylelib/`
52+
- LaTeX style definitions in `tex/customcolors.sty` and `tex/mplstyle.sty`
53+
54+
4. **Helper Functions**: Some scripts use helper modules like `nyt-helper-data.py`, `rps-br-helper.py`, and `speedo-functions.py`
55+
56+
## Working with Figures
57+
58+
When modifying or creating figures:
59+
1. Python scripts should save outputs to the appropriate `figures/` subdirectory
60+
2. Use consistent naming between .py files and their .pdf outputs
61+
3. Many scripts demonstrate specific matplotlib techniques mentioned in the book text

‎blake_plate_8.png‎

6.29 MB
Loading

‎jupyterbook/README.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Matplotlib for Storytellers - Jupyter Book
2+
3+
This is the Jupyter Book version of Chapter 1: The Object-oriented Interface from "Matplotlib for Storytellers".
4+
5+
## Building the Book
6+
7+
1. Install dependencies:
8+
```bash
9+
pip install -r requirements.txt
10+
```
11+
12+
2. Build the book:
13+
```bash
14+
jupyter-book build .
15+
```
16+
17+
3. View the book:
18+
```bash
19+
open _build/html/index.html
20+
```
21+
22+
## Structure
23+
24+
- `_config.yml` - Book configuration
25+
- `_toc.yml` - Table of contents
26+
- `intro.md` - Welcome page
27+
- `chapter1/` - Chapter 1 content
28+
- `index.md` - The Object-oriented Interface chapter
29+
- `images/` - Figure PDFs from the original book
30+
31+
## Notes
32+
33+
- Code blocks are standard markdown with Python syntax highlighting
34+
- Images have been converted to PNG format for better web display
35+
- The content faithfully follows the original LaTeX version
36+
- Note: Some code examples assume previous imports (e.g., `import matplotlib.pyplot as plt`, `import numpy as np`, `import pandas as pd`)

‎jupyterbook/_config.yml‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# Book settings
2+
title: Matplotlib for Storytellers
3+
author: Alexander Clark
4+
copyright: "2025"
5+
6+
# Force re-execution of notebooks on each build.
7+
# See https://jupyterbook.org/content/execute.html
8+
execute:
9+
execute_notebooks: auto
10+
exclude_patterns:
11+
- 'pattern_to_exclude'
12+
timeout: 100
13+
allow_errors: false
14+
15+
# Define the name of the latex output file for PDF builds
16+
latex:
17+
latex_documents:
18+
targetname: book.tex
19+
20+
# Add a bibtex file so that we can create citations
21+
# bibtex_bibfiles:
22+
# - references.bib
23+
24+
# Information about where the book exists on the web
25+
repository:
26+
url: https://github.com/alexanderthclark/Matplotlib-for-Storytellers
27+
branch: jupyterbook-chapter1
28+
path_to_book: jupyterbook
29+
30+
# Add GitHub buttons to your book
31+
html:
32+
use_edit_page_button: true
33+
use_repository_button: true
34+
use_issues_button: true
35+
favicon: "_static/favicon.ico"
36+
extra_footer: |
37+
<p>
38+
This version: {date}<br>
39+
Built with <a href="https://jupyterbook.org">Jupyter Book</a>
40+
</p>
41+
analytics:
42+
google_analytics_id: ""
43+
home_page_in_navbar: true
44+
45+
# Jupyter Book theme and appearance
46+
sphinx:
47+
config:
48+
# html_theme: book
49+
html_theme_options:
50+
repository_url: "https://github.com/alexanderthclark/Matplotlib-for-Storytellers"
51+
use_repository_button: true
52+
use_issues_button: true
53+
use_edit_page_button: true
54+
navbar_align: "left"
55+
show_toc_level: 2
56+
navigation_with_keys: false
57+
language: en
58+
mathjax_path: https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
59+
html_extra_path:
60+
- _static
61+
extra_extensions:
62+
- sphinx_design
63+
64+
# Launch buttons for interactive content
65+
launch_buttons:
66+
notebook_interface: classic
67+
binderhub_url: ""
68+
jupyterhub_url: ""
69+
thebe: false
70+
colab_url: "https://colab.research.google.com"

0 commit comments

Comments
 (0)