Set up literate programming structure

2026-04-07 09:55:41 -07:00
commit 2d36400ba0
16 changed files with 933 additions and 0 deletions
@@ -0,0 +1,77 @@
+This is a monorepo aimed at developers building nostr applications in rust. All crates are prefixed by the namespace `coracle`.
+
+It has the following crates:
+
+- `coracle-lib` - Struct definitions, stateless utilities related to nostr.
+- `coracle-net` - Networking utilities for working with relays
+- `coracle-signer` - Signer client/server utilities
+- `coracle-content` - Text parsing and rendering utilities
+- `coracle-storage` - Storage adapters for different platforms
+
+All code is written in a [literate programming](https://en.wikipedia.org/wiki/Literate_programming) style and compiled to both html documentation and rust source code. The goal of this repository is threefold:
+
+- To create a complete resource for learning how to work with the nostr protocol for humans
+- To create a production-ready nostr utility library for inclusion in rust, KMP, and web projects.
+- To experiment with using literate programming to serve both as a library and context file for LLMs.
+
+## Prerequisites
+
+- [Rust](https://rustup.rs/)
+- [just](https://github.com/casey/just)
+- [mdbook](https://rust-lang.github.io/mdBook/) (`cargo install mdbook`)
+
+## How it works
+
+The source of truth is the `book/` directory, which contains markdown files written in a literate programming style. Code blocks annotated with a file path are extracted ("tangled") into Rust source files by the `coracle-tangle` tool.
+
+For example, a code block like this in a markdown file:
+
+```text
+  ```rust {file=coracle-lib/src/event.rs}
+  pub struct Event { ... }
+  ```
+```
+
+will be extracted to `coracle-lib/src/event.rs`. Multiple blocks targeting the same file are concatenated in document order, so you can introduce a struct in one section and add methods to it later in the narrative.
+
+Code blocks without a `{file=...}` annotation are illustrative only and are not tangled.
+
+The `src/` directories of the library crates are generated artifacts and should not be edited directly. Edit the markdown in `book/` instead.
+
+## Usage
+
+```sh
+# Tangle: extract code from markdown into .rs files
+just tangle
+
+# Build: tangle + compile all library crates
+just build
+
+# Check: tangle + type-check without full compilation
+just check
+
+# Weave: tangle + generate the HTML book (output in target/book/)
+just weave
+
+# Clean: remove all generated source and book output
+just clean
+
+# All: build + weave
+just all
+```
+
+## Project structure
+
+```
+book/               # Literate source (the single source of truth)
+  book.toml         # mdBook configuration
+  SUMMARY.md        # Table of contents
+  01-introduction.md
+  02-events.md      # etc.
+coracle-tangle/     # The tangle/weave tool (Rust binary)
+coracle-lib/        # Core nostr types and utilities (generated src/)
+coracle-net/        # Relay networking (generated src/)
+coracle-signer/     # Signing abstractions (generated src/)
+coracle-content/    # Content parsing (generated src/)
+coracle-storage/    # Storage adapters (generated src/)
+```