148 lines
3.8 KiB
Markdown
148 lines
3.8 KiB
Markdown
# AGENTS.md - Guidelines for JuliaKurs23
|
|
|
|
This is a **Quarto-based Julia programming course book**. The book teaches scientific computing with Julia using interactive Jupyter notebooks rendered with Quarto.
|
|
|
|
**Translation Note:** The book was originally written in German and translated to English. The English needs improvement—focus on making the prose professional, concise, and suitable for mathematicians.
|
|
|
|
## Project Overview
|
|
|
|
- **Type**: Educational book (HTML website + PDF) generated from Quarto (.qmd) files
|
|
- **Language**: English (all content)
|
|
- **Build System**: Quarto with Julia Jupyter kernel
|
|
- **Julia Version**: 1.10
|
|
- **License**: CC BY-NC-SA 4.0
|
|
|
|
---
|
|
|
|
## Current Task: English Translation Improvement
|
|
|
|
The English text in this book was translated from German and needs refinement for quality.
|
|
|
|
### Workflow (one change at a time)
|
|
|
|
For each chapter file in `chapters/`:
|
|
|
|
1. I read the file and identify English improvements
|
|
2. I present ONE improvement at a time showing:
|
|
- The current text
|
|
- The proposed improvement
|
|
- Explanation of why the change is needed
|
|
3. You reply **yes** or **no**
|
|
4. If yes, I apply the change; if no, I skip it
|
|
5. Repeat until all improvements for that file are done
|
|
6. Move to the next chapter file
|
|
|
|
### What to improve:
|
|
- English prose, grammar, word choice
|
|
- Clarity and flow for mathematical audience
|
|
- Professional tone suitable for mathematicians/scientists
|
|
|
|
### What NOT to change:
|
|
- Julia code
|
|
- LaTeX equations
|
|
- Markdown formatting
|
|
- Quarto cell options (`#| eval:`, etc.)
|
|
|
|
---
|
|
|
|
## Build Commands
|
|
|
|
```bash
|
|
# Build HTML website
|
|
quarto render
|
|
|
|
# Build only HTML
|
|
quarto render --to julia-color-html
|
|
|
|
# Build only PDF
|
|
quarto render --to julia-color-pdf
|
|
|
|
# Preview locally
|
|
quarto preview
|
|
|
|
# Render a specific chapter
|
|
quarto render chapters/first_contact.qmd
|
|
|
|
# Run in daemon mode (faster rebuilds)
|
|
quarto render --execute-daemon 3600
|
|
```
|
|
|
|
### Deployment
|
|
|
|
```bash
|
|
./deploy.sh
|
|
```
|
|
|
|
---
|
|
|
|
## Code Style Guidelines
|
|
|
|
### Quarto Structure (.qmd files)
|
|
|
|
- All `.qmd` files start with YAML front matter: `engine: julia`
|
|
- Code blocks use triple backticks with `julia` identifier
|
|
- Cell options in comments: `#| option: value`
|
|
|
|
### Julia Code Conventions
|
|
|
|
**Imports:**
|
|
```julia
|
|
using Statistics, LinearAlgebra, Plots # many exports
|
|
import Base: convert, show # specific exports
|
|
```
|
|
|
|
**Naming:**
|
|
- Variables/functions: lowercase with underscores (`my_variable`)
|
|
- Types: CamelCase (`MyType`, `AbstractMatrix`)
|
|
- Constants: ALL_UPPERCASE (`MAX_ITER`)
|
|
- Modules: PascalCase (`Statistics`)
|
|
|
|
**Formatting:**
|
|
- 4 spaces indentation
|
|
- ~92 character line limit
|
|
- Spaces around operators: `a + b`
|
|
- No spaces before commas: `f(a, b)`
|
|
|
|
**Types:**
|
|
- Explicit types for performance/clarity
|
|
- Parameterize: `Vector{Float64}`, `Dict{Symbol, Int}`
|
|
- Concrete types for struct fields
|
|
|
|
**Error Handling:**
|
|
```julia
|
|
try
|
|
parse(Int, user_input)
|
|
catch e
|
|
println("Invalid input: $e")
|
|
end
|
|
|
|
@assert x >= 0 "x must be non-negative"
|
|
```
|
|
|
|
---
|
|
|
|
## File Organization
|
|
|
|
```
|
|
/
|
|
├── _quarto.yml # Quarto configuration
|
|
├── Project.toml # Julia dependencies
|
|
├── index.qmd # Book index
|
|
├── chapters/ # Chapter .qmd files
|
|
├── notebooks/ # Jupyter notebooks (.ipynb)
|
|
├── css/ # Custom styles
|
|
├── images/ # Images and logos
|
|
├── fonts/ # Custom fonts
|
|
└── _book/ # Built output (generated)
|
|
```
|
|
|
|
---
|
|
|
|
## Important Notes
|
|
|
|
1. **All content is in English** — professional, concise, suitable for mathematicians
|
|
2. **Code, LaTeX, formatting preserved** — only improve English prose
|
|
3. **Code execution cached** — use `#| eval: true` to execute cells
|
|
4. **Freeze mode** — set to `auto` in _quarto.yml; use `freeze: false` to re-run all code
|
|
5. **Keep intermediates** — `keep-ipynb`, `keep-tex`, `keep-md` are all true
|