|
1 | | -# CLAUDE.md |
| 1 | +# Claude Code Guidance |
2 | 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 | | -**F# Advent 2025 blog post project** demonstrating Fable.Python capabilities. |
8 | | - |
9 | | -**Fable.Literate** is a literate programming converter (inspired by jupytext) written in F# that transpiles to Python via Fable.Python. It processes `.fs` files with embedded Markdown comments (FSharp.Formatting conventions) and outputs GitHub-flavored Markdown suitable for publishing on platforms like Hashnode. |
10 | | - |
11 | | -**Key concept:** The project is self-documenting - the chapters and converter generate the blog post that documents how they work. |
12 | | - |
13 | | -## Build Commands (using just) |
14 | | - |
15 | | -```bash |
16 | | -just setup # Install Fable and Python dependencies |
17 | | -just restore # Restore NuGet packages |
18 | | -just build # Build all chapters and tools to Python |
19 | | -just generate # Generate individual markdown docs from chapters |
20 | | -just blogpost # Generate concatenated blogpost.md for publishing |
21 | | -just format # Format Python with ruff |
22 | | -just lint # Lint Markdown (markdownlint) |
23 | | -just watch # Watch mode for development |
24 | | -just clean # Clean generated files |
25 | | -just all # Full pipeline: restore, build, generate, format, lint |
26 | | -``` |
27 | | - |
28 | | -## Architecture |
29 | | - |
30 | | -### Fable.Literate AST Pipeline |
31 | | - |
32 | | -The converter follows a compiler-like architecture with three phases: |
33 | | - |
34 | | -1. **Parse**: Convert source lines into a Block AST |
35 | | -2. **Transform**: Filter hidden blocks, resolve Python includes |
36 | | -3. **Print**: Render the AST as Markdown |
37 | | - |
38 | | -### Literate Directives |
39 | | - |
40 | | -| Directive | Purpose | |
41 | | -|-----------|---------| |
42 | | -| `(** content *)` | Raw markdown content | |
43 | | -| `(*** hide ***)` | Hide following code from output | |
44 | | -| `(*** include-python: symbol ***)` | Include generated Python for symbol | |
45 | | -| Regular F# code | Wrapped in ```fsharp fenced blocks | |
46 | | - |
47 | | -### File Structure |
48 | | - |
49 | | -```text |
50 | | -chapters/ |
51 | | -├── Introduction.fs # What is Fable.Python, why use it |
52 | | -├── Python.fs # F# concepts for Python developers |
53 | | -├── GettingStarted.fs # Setup, first project, hello world |
54 | | -├── Interop.fs # Using existing Python libraries |
55 | | -├── Bindings.fs # Creating Python bindings |
56 | | -├── Compatibility.fs # F# features supported, limitations |
57 | | -├── AsyncProgramming.fs # async vs task, Python asyncio mapping |
58 | | -├── Testing.fs # Testing F# code with Python test runners |
59 | | -├── FableV5.fs # Fable v5 features, Rust core, PyPI |
60 | | -├── Pydantic.fs # Pydantic models, DTOs, validation |
61 | | -├── FastAPI.fs # Type-safe web APIs with FastAPI |
62 | | -├── UnitsOfMeasure.fs # Compile-time dimensional analysis |
63 | | -├── FableLiterate.fs # Symlink → ../Fable.Literate/App.fs |
64 | | -└── Summary.fs # Wrap-up, resources, repo link |
65 | | -Fable.Literate/ |
66 | | -├── App.fs # Fable.Literate converter source (F#) |
67 | | -└── Fable.Literate.fsproj |
68 | | -output/ |
69 | | -├── chapters/ # Generated Python from chapters |
70 | | -└── Fable.Literate/ |
71 | | - └── app.py # Generated converter (Python) |
72 | | -docs/ |
73 | | -├── *.md # Individual chapter markdown |
74 | | -└── blogpost.md # Concatenated for Hashnode |
75 | | -``` |
76 | | - |
77 | | -## Chapter Writing Guidelines |
78 | | - |
79 | | -- Each chapter is a literate F# file with embedded markdown |
80 | | -- Use `(** ... *)` for markdown content |
81 | | -- Use `(*** hide ***)` to hide setup code (module declarations, imports) |
82 | | -- Use `(*** include-python: symbolName ***)` to show generated Python |
83 | | -- Tables are auto-formatted by markdownlint - don't fight it |
84 | | -- Keep code examples self-contained and buildable |
85 | | - |
86 | | -## Fable.Python Considerations |
87 | | - |
88 | | -- Use `Fable.Core` attributes (`[<Emit>]`, `[<Import>]`, etc.) |
89 | | -- Use `Fable.Python.Pydantic` for Pydantic interop |
90 | | -- Stick to Fable-compatible F# subset |
91 | | -- `task { }` compiles to native Python `async def` (Fable v5) |
92 | | -- `async { }` for multi-target code (Python, .NET, JS) |
93 | | - |
94 | | -## Resources |
95 | | - |
96 | | -- [Fable.Python docs](https://fable.io/docs/getting-started/python.html) |
97 | | -- [Fable.Python GitHub](https://github.com/fable-compiler/Fable.Python/) |
98 | | -- [Content Plan](CONTENT-PLAN.md) - Chapter structure and TODO items (important!) |
| 3 | +Follow the repository-wide contributor and agent instructions in [AGENTS.md](AGENTS.md). |
0 commit comments