📜 feat: README

Author: tkr-sh

README.md

@@ -0,0 +1,97 @@
+# lua-std-doc
+
+**The Lua 5.5 standard library, documented by rustdoc.**
+
+This repository abuses `rustdoc` as a documentation generator for a
+language it has never heard of. A small Rust crate models Lua's world
+and a client-side script rewrites rustdoc's vocabulary on the fly. The result
+is a browsable, searchable, cross-linked reference for Lua 5.5, with
+rustdoc's search index, sidebar, and theming intact.
+
+📖 **Live**: <https://tkr-sh.github.io/lua-std-doc/>
+
+## The extended library
+
+Beyond the standard reference, the `extended` cargo feature documents
+**`lua/extended.lua`**: 34 functions other languages ship in their
+standard libraries (inspired by Rust), implemented, tested, and usable
+today:
+
+```lua
+require("extended")
+
+("a,b,c"):split(",")            --> { "a", "b", "c" }
+("  hi "):trim()                --> "hi"
+table.map({1, 2, 3}, f)
+table.fold(t, f, init)
+math.clamp(x, 1, 10)
+print(inspect({ nested = { ok = true } }))
+```
+
+`lua/extended.min.lua` is the same library on a single line (Lua's
+grammar is newline-free once `--` comments are gone), and
+`lua/test_extended.lua` is the assertion suite covering both:
+
+```console
+$ cd lua && lua5.4 test_extended.lua
+$ cd lua && EXT=extended.min.lua lua5.4 test_extended.lua
+```
+
+
+## How the trick works
+
+| Rust concept          | Rendered as                                      |
+| --------------------- | ------------------------------------------------ |
+| `pub struct string;`  | `data type string`                               |
+| `pub trait tostring`  | `metatable tostring` (metamethods as functions)  |
+| `impl` blocks         | *Method form* vs *Library functions* sections    |
+| `Repeatable<T>` param | `...values: T` (Lua varargs)                     |
+| `option<T>`           | `T \| nil`, with `nil` linked to its type page  |
+| `<T: tostring>`       | a clickable metatable bound                      |
+| modules               | libraries (`math`, `io`, `os`, `coroutine`, ...) |
+
+The machinery lives in three files:
+
+- **`custom.html`**: injected into every page via `--html-in-header`.
+  Swaps rustdoc's vocabulary (`pub fn` → `function`, `Trait` →
+  `Metatable`, ...), rewrites the marker generics above at the HTML
+  level so type links survive, and ships a small Lua syntax highlighter
+  that emits rustdoc's own token classes (`kw`, `string`, `number`,
+  `comment`), so both themes color Lua code through their existing
+  variables. It cooperates with rustdoc's *line numbers* setting in
+  both orderings.
+- **`lua.css`**: the theme, and the extension stylesheet
+  (`--extend-css`): hides Rust-only sections (auto traits, blanket
+  impls), styles the logo and the function-call highlight class.
+- **`src/*.rs`**: the reference itself, one file per library, in an
+  MDN-ish per-function format: summary, Parameters, Return value,
+  Description, Examples (every function has one, with outputs matching
+  Lua 5.5's round-trip float printing), See also.
+
+## Building
+
+Docs require **nightly** (pinned by `rust-toolchain.toml`) for
+`doc_auto_cfg`, which renders the "Available on crate feature
+`extended` only" badges; everything else is stable Rust.
+
+```console
+$ just docs        # or the cargo rustdoc line from the justfile
+$ open target/doc/lua_std/index.html
+```
+
+## Deploying
+
+`.github/workflows/deploy.yml` tests the Lua library, builds the site
+on nightly, and publishes `target/doc/` to GitHub Pages on every push
+to `main`. One-time setup: repository **Settings → Pages → Source →
+GitHub Actions**.
+
+## Credits
+
+- Lua and the Lua logo are from [Lua.org](https://www.lua.org/); logo
+  © 1998 Lua.org, graphic design by Alexandre Nakonechnyj.
+- Reference content follows the
+  [Lua 5.5 manual](https://www.lua.org/manual/5.5/), rephrased and
+  with original examples.
+- Per-function page structure inspired by
+  [luadocs.com](https://www.luadocs.com/).