Skip to content

Commit 9b769bc

Browse files
committed
fix: Cleanup Claude setup and move to agent agnostic setup
1 parent cf2afec commit 9b769bc

3 files changed

Lines changed: 172 additions & 12 deletions

File tree

.claude/settings.local.json

Lines changed: 0 additions & 12 deletions
This file was deleted.

.gitignore

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -130,3 +130,6 @@ _build
130130

131131
# macos
132132
.DS_Store
133+
134+
# Claude
135+
.claude

AGENTS.md

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
# AGENTS.md
2+
3+
This file provides guidance to coding agents when working with
4+
code in this repository.
5+
6+
## Project Overview
7+
8+
**Selbstlernkurs Python** - A self-learning Python course for library and
9+
information science students at Humboldt-Universität zu Berlin. The course uses
10+
MyST Markdown and Jupyter Book to create an interactive learning environment.
11+
12+
**Target Audience**: Master's students in Library and Information Science
13+
(distance learning program)
14+
15+
**Course Structure**: Project-based learning with library/information science
16+
use cases (CSV processing, MARC-XML metadata, Excel statistics)
17+
18+
## Repository Architecture
19+
20+
### Chapter Organization
21+
22+
Numbered directories represent sequential course modules:
23+
24+
- `000-Einleitung/` - Introduction and course usage
25+
- `010-Installation_Technik/` - Python installation and setup
26+
- `020-Projekt_Taschenrechner_I/` - Calculator project I (basic concepts)
27+
- `030-Exkurs_Unix/` - Unix command line excursion
28+
- `040-Projekt_CSV_I/` - CSV file processing
29+
- `045-Projekt_Taschenrechner_II/` - Calculator project II (input, loops)
30+
- `050-Exkurs_Git/` - Git version control excursion
31+
- `060-Projekt_CSV_II/` - Advanced CSV processing
32+
- `070-Projekt_MARC-XML/` - Library metadata processing
33+
- `080-Projekt_Excel/` - Excel file processing
34+
- `900-Cheatsheet.md` - Quick reference
35+
- `999-Epilog/` - Glossary, index, literature, imprint
36+
37+
### Key Directories
38+
39+
- `solutions/` - Solution scripts for exercises (e.g.,
40+
`solutions/020/taschenrechner.py`)
41+
- `_build/` - Generated build output (do not edit manually)
42+
- `.venv/` - Python virtual environment (Python 3.13+)
43+
- `assets/` - Images, logos, and static files
44+
45+
### Content Format
46+
47+
Each chapter contains:
48+
49+
- `.ipynb` files - Interactive Jupyter notebooks with executable code
50+
- `.md` files - MyST Markdown documentation
51+
- Learning objectives (🎓 Lernziele) at the start
52+
- Exercises that qualify as "Kleine Aufgabe" course assignments
53+
54+
Content is in German using gender-neutral language with asterisks (e.g.,
55+
"Lernende\*r")
56+
57+
## Common Development Commands
58+
59+
### Environment Setup
60+
61+
```bash
62+
# Activate virtual environment (automatic with direnv via .envrc)
63+
source .venv/bin/activate
64+
65+
# Install/update dependencies
66+
pip install -r requirements.txt
67+
```
68+
69+
**Dependencies** (Python 3.13+):
70+
71+
- `jupyter-book==2.0.0b3` ⚠️ Beta version - may have unstable APIs
72+
- `jupyterlab`, `ipywidgets`, `jupyterquiz`, `numpy`
73+
74+
### Building and Testing
75+
76+
```bash
77+
# Build the complete MyST book (outputs to _build/)
78+
jupyter book build --execute --all
79+
80+
# Start JupyterLab for editing notebooks
81+
jupyter lab
82+
# or: .venv/bin/jupyter lab
83+
84+
# Run solution scripts
85+
./solutions/020/taschenrechner.py
86+
# or: python3 solutions/020/taschenrechner.py
87+
```
88+
89+
## Key Technical Details
90+
91+
### MyST Book Configuration (`myst.yml`)
92+
93+
- **Project ID**: `009c9d71-a4fc-4438-8118-31289551ac9b`
94+
- **Template**: `book-theme` with custom logo/favicon in `assets/`
95+
- **Table of Contents**: Defined in `toc.yml` with hierarchical chapter
96+
structure
97+
- **Jupyter Integration**:
98+
- Jupyter Lite enabled (browser-based Python execution)
99+
- Binder integration (cloud-based interactive notebooks via mybinder.org)
100+
- **License**: CC-BY-4.0 (content) / MIT (code)
101+
- **Bibliography**: `bibliography.bib` for citations
102+
103+
### Adding New Content
104+
105+
When adding chapters or sections:
106+
107+
1. Create files in the appropriate numbered directory (e.g.,
108+
`040-Projekt_CSV_I/`)
109+
2. Update `toc.yml` to include the new file in the navigation hierarchy
110+
3. Follow MyST frontmatter conventions for metadata:
111+
```yaml
112+
---
113+
short_title: Title
114+
numbering:
115+
heading_1: true
116+
heading_2: true
117+
title: true
118+
---
119+
```
120+
4. Use margin notes for hints: `:::::{margin} ... :::::`
121+
5. Include learning objectives (🎓 Lernziele) at the start of chapters
122+
123+
### Jupyter Notebooks
124+
125+
- Use MyST markdown cells (not plain markdown) for rich formatting
126+
- Include interactive Python examples with expected outputs
127+
- Use `jupyterquiz` for in-notebook quizzes and exercises
128+
- Notebooks support Mermaid diagrams for visualizations
129+
- Comment syntax: `# Comment text` (everything after `#` is ignored)
130+
131+
### Python Solution Scripts
132+
133+
Pattern for solution files (see `solutions/020/taschenrechner.py`):
134+
135+
- Include shebang: `#! /usr/bin/env python3`
136+
- Make executable: `chmod +x script.py`
137+
- Follow PEP 8 style guidelines
138+
- Use `if __name__ == "__main__":` for executable logic
139+
140+
### Language and Style
141+
142+
**German content with specific conventions**:
143+
144+
- Gender-neutral asterisks: "Lernende\*r", "Bibliothekswissenschaftler\*innen"
145+
- German terms with English in parentheses: "Versionskontrolle (Version
146+
Control)"
147+
- File/folder names may include umlauts: `Dateien_öffnen.ipynb`
148+
- Decimal numbers: German text style in prose, Python dot notation in code
149+
150+
### Pedagogical Structure
151+
152+
**Project-based, incremental learning**:
153+
154+
- **Iterative complexity**: Projects revisited with added features (e.g.,
155+
`Taschenrechner` I & II)
156+
- **Domain-specific context**: All examples use library/information science
157+
data
158+
- **Self-paced design**: Students can skip ahead or follow linear progression
159+
- **Mixed formats**: Notebooks (hands-on), Markdown (theory), Excursions
160+
(context)
161+
162+
## Development Notes
163+
164+
- **Never edit `_build/`** - regenerated on each build
165+
- **Ignore `.ipynb_checkpoints/`** - Jupyter autosave artifacts
166+
- **Beta warning**: `jupyter-book==2.0.0b3` may have breaking changes in
167+
updates
168+
- **Binder deployment**: Changes to main branch automatically available in
169+
cloud environment

0 commit comments

Comments
 (0)