|
| 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