fix: Updated text and improved code extraction

Author: dbrattli

chapters/bindings.fs

@@ -34,9 +34,9 @@ let json: IExports = nativeOnly
 (**
 This generates: `import json`
 
-The `[<Erase>]` attribute means the interface only exists at compile time -
-no code is generated for it. The `nativeOnly` placeholder tells Fable the
-value will be resolved at runtime.
+The `[<Erase>]` attribute means the interface only exists at compile time
+(erased = no code generated for it). The `nativeOnly` placeholder tells Fable
+the value will be resolved at runtime.
 
 ## Import Attributes
 
@@ -107,7 +107,8 @@ let upper (s: string) : string = nativeOnly
 (**
 ## Function Overloads
 
-**Prefer overloads over erased unions.** Instead of:
+**Why prefer overloads over erased unions?** Erased unions like `U2<string, bytes>`
+require callers to wrap values explicitly, creating friction. Instead of:
 
 ```fsharp
 // ❌ Avoid this - creates friction for callers

chapters/compatibility.fs

@@ -3,9 +3,8 @@ module Compatibility
 (**
 # F# Compatibility in Fable.Python
 
-Understanding what works and what doesn't is crucial when targeting Python
-with Fable. This chapter covers supported features, limitations, and
-important differences from .NET.
+This chapter covers supported features, limitations, and important differences
+from .NET when targeting Python with Fable.
 
 ## Common Types and Objects
 
@@ -94,6 +93,11 @@ let mutableList = ResizeArray<int>()
 (*** include-python: greeting, is_enabled, coordinates, numbers, mutable_list ***)
 
 (**
+Each of these F# values compiles to its Python equivalent. Strings become `str`,
+booleans become `bool`, and tuples become Python tuples. The F# `list` uses the
+fable-library implementation for immutable semantics, while `ResizeArray`
+compiles directly to Python's mutable `list`.
+
 ### Functions and Lambdas
 
 First-class functions work as expected:
@@ -106,6 +110,10 @@ let applyTwice f x = f (f x)
 let result = applyTwice (add 1) 5 // 7
 
 (**
+Functions are first-class values in F#. The `applyTwice` function takes another
+function `f` as a parameter and applies it twice. Partial application works
+naturally - `(add 1)` creates a new function that adds 1 to its argument.
+
 ### Pattern Matching
 
 Full pattern matching support:

chapters/fable-v5.fs

@@ -30,8 +30,7 @@ The Python target has received special attention in v5:
 ## Rust Core with PyO3
 
 One of the biggest changes is that the core of fable-library is now written
-in **Rust** using PyO3. This isn't primarily for performance - it's for
-**correctness**:
+in **Rust** using PyO3. The motivation is **correctness**, not performance:
 *)
 
 (*** hide ***)
@@ -94,5 +93,5 @@ Then compile your F# to Python:
 dotnet fable YourProject.fsproj --lang python -o output/
 ```
 
-The generated Python code will be modern, type-hinted, and ready to run!
+The generated Python code will be modern, type-hinted, and ready to run.
 *)

chapters/getting-started.fs

@@ -40,8 +40,12 @@ Fable-generated Python code requires the `fable-library` runtime:
 pip install "fable-library==5.0.0a17"
 ```
 
-> **Note:** Version pinning is important! The fable-library version must match
-> your Fable compiler version. PyPI uses `5.0.0a17` format instead of `5.0.0-alpha.17`.
+---
+
+**Note:** Version pinning matters. The fable-library version must match
+your Fable compiler version. PyPI uses `5.0.0a17` format instead of `5.0.0-alpha.17`.
+
+---
 
 ## Your First Program
 

chapters/interop.fs

@@ -62,6 +62,9 @@ let length = builtins.len [ 1; 2; 3 ]
 let absValue = builtins.abs (-42)
 
 (**
+The `builtins` module provides typed access to Python's built-in functions.
+These calls compile directly to `len([1, 2, 3])` and `abs(-42)` in Python.
+
 ### Working with sys Module
 *)
 
@@ -79,6 +82,9 @@ let fileName = os.path.basename "/path/to/file.txt"
 let dirName = os.path.dirname "/path/to/file.txt"
 
 (**
+The `os.path` functions work with arrays of path segments. These compile to
+Python's `os.path.join`, `os.path.basename`, and `os.path.dirname` calls.
+
 ## Environment Variables
 
 Use `os.getenv` to safely retrieve environment variables:
@@ -292,18 +298,11 @@ type DecoratedUser() =
     member val Name: string = "" with get, set
     member val Age: int = 0 with get, set
 
-(**
-This generates:
+(** This generates: *)
 
-```python
-from dataclasses import dataclass
-
-@dataclass
-class DecoratedUser:
-    Name: str = ""
-    Age: int = 0
-```
+(*** include-python: DecoratedUser ***)
 
+(**
 ## Class Attributes and DataClasses
 
 ### Py.ClassAttributes
@@ -316,15 +315,11 @@ type PydanticModel() =
     member val Name: string = "" with get, set
     member val Age: int = 0 with get, set
 
-(**
-This generates class-level type annotations suitable for Pydantic:
+(** This generates class-level type annotations suitable for Pydantic: *)
 
-```python
-class PydanticModel:
-    Name: str = ""
-    Age: int = 0
-```
+(*** include-python: PydanticModel ***)
 
+(**
 ### Py.DataClass Shorthand
 
 `Py.DataClass` is shorthand for `ClassAttributes(Attributes, false)`:

chapters/introduction.fs

@@ -39,29 +39,33 @@ Fable.Python is a great choice when:
 ## When NOT to Use Fable.Python
 
 - When your F# code depends on .NET libraries without Fable support
-- Performance-critical code (Python is still slow)
+- Performance-critical code (Python has runtime overhead)
 - Team won't learn F#
 
 **Best fit:** You love F#, but need Python's ecosystem.
 
-## A Simple Example
+## A First Example
 
-Let's start with something simple. Here's F# code that will compile to Python:
+Let's start with F# code that compiles to Python:
 *)
 
 let greet name = $"Hello, {name}!"
 
 let message = greet "Fable.Python"
 
 (**
-When compiled with Fable, this generates clean, readable Python:
+When compiled with Fable, this generates the following Python:
+*)
 
-```python
-def greet(name):
-    return f"Hello, {name}!"
+(*** include-python: greet, message ***)
 
-message = greet("Fable.Python")
-```
+(**
+The `name: Any | None = None` signature may look odd at first. This happens because
+F# infers the type from usage - since we only call `greet` with a string, the compiler
+doesn't know if it might also be called with unit `()` (no argument). If it were,
+Python would call it as `greet()` instead of `greet("Fable.Python")`. Adding an
+explicit type annotation `let greet (name: string) = ...` would generate a cleaner
+`name: str` parameter.
 
 ## The Power of Types
 
@@ -82,9 +86,11 @@ let shapes = [ Circle 5.0; Rectangle(3.0, 4.0) ]
 let totalArea = shapes |> List.sumBy area
 
 (**
-This compiles to Python while preserving the semantic meaning. The discriminated
-union becomes a tagged class structure, and pattern matching becomes clean
-conditional logic.
+This compiles to Python while preserving the semantic meaning. The `Shape` type
+becomes a tagged class structure, and the `match` expression becomes clean
+conditional logic. The compiler ensures you handle all cases - if you add a
+new shape variant, the compiler will warn you about unhandled cases in
+the `area` function.
 
 ## What's Next?
 
@@ -94,5 +100,5 @@ In the following chapters, we'll cover:
 - **Bindings** - Working with Python libraries from F#
 - **Compatibility** - Understanding what F# features are supported
 
-Let's dive in!
+Let's begin.
 *)

chapters/python.fs

@@ -3,9 +3,9 @@ module ForPythonDevelopers
 (**
 # Are You a Python Developer?
 
-If you're coming from Python, welcome! This chapter will help you understand
-the F# code you'll see throughout this guide. Don't worry - F# is more
-approachable than it might first appear, and many concepts will feel familiar.
+If you're coming from Python, welcome. This chapter will help you understand
+the F# code you'll see throughout this guide. F# is more approachable than
+it might appear, and many concepts are familiar.
 
 ## What is F#?
 
@@ -104,8 +104,8 @@ let area shape =
     | Rectangle(width, height) -> width * height
 
 (**
-The compiler will warn you if you forget to handle a case. No more runtime
-`AttributeError` because you forgot a shape type!
+The compiler warns you if you forget to handle a case. No more runtime
+`AttributeError` because you forgot a shape type.
 
 ### Records
 

chapters/units-of-measure.fs

@@ -48,7 +48,7 @@ let speed = distance / time // Automatically inferred as float<m/s>
 
 (**
 The compiler tracks units through all operations. Division of meters by
-seconds gives meters-per-second. This is all checked at compile time!
+seconds gives meters-per-second. This is all checked at compile time.
 
 ## Preventing Errors
 
@@ -58,7 +58,7 @@ Try to add incompatible units and the compiler stops you:
 let distance = 100.0<m>
 let mass = 50.0<kg>
 
-// This won't compile!
+// This won't compile:
 // let nonsense = distance + mass
 // Error: The unit of measure 'm' does not match 'kg'
 ```

docs/bindings.md

@@ -31,9 +31,9 @@ let json: IExports = nativeOnly
 
 This generates: `import json`
 
-The `[<Erase>]` attribute means the interface only exists at compile time -
-no code is generated for it. The `nativeOnly` placeholder tells Fable the
-value will be resolved at runtime.
+The `[<Erase>]` attribute means the interface only exists at compile time
+(erased = no code generated for it). The `nativeOnly` placeholder tells Fable
+the value will be resolved at runtime.
 
 ## Import Attributes
 
@@ -104,7 +104,8 @@ let upper (s: string) : string = nativeOnly
 
 ## Function Overloads
 
-**Prefer overloads over erased unions.** Instead of:
+**Why prefer overloads over erased unions?** Erased unions like `U2<string, bytes>`
+require callers to wrap values explicitly, creating friction. Instead of:
 
 ```fsharp
 // ❌ Avoid this - creates friction for callers