diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index d0f0b11..621418f 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -1,59 +1,105 @@ name: docs +# Every documentation version is a separate Hugo build, published under +# https://go-ruby-yaml.github.io/docs// on the gh-pages branch, where is +# the minor version of the code the pages describe (params.docs.version in +# hugo.yaml: v0.3.1 -> 0.3), or "main" while no release is tagged. Each push to +# main replaces that version's path and leaves the others alone. Pull requests +# build and check, and publish nothing. +# +# ⛔ This replaced MkDocs Material plus mike: a Python toolchain, a +# requirements.txt and a pip install to render a static site for a pure-Go +# organisation. + on: push: branches: [main] pull_request: workflow_dispatch: -# The build needs nothing beyond the source. Write access to the repository -# is granted to the deploy job alone, below, so a pull request build cannot -# push to gh-pages. permissions: contents: read +env: + HUGO_VERSION: "0.167.0" + # sha256 of hugo_${HUGO_VERSION}_linux-amd64.tar.gz, from the release's checksums.txt. + HUGO_SHA256: "4d84519b9f619e6d4c3fb45a50157abeabeb724f859c60605f44c23def6e1169" + DOCS_URL: "https://go-ruby-yaml.github.io/docs" + jobs: - # Build on every pull request as well as on main, so a change to the docs or to - # the toolchain in requirements.txt has to prove it still builds before it - # lands. Without this the workflow ran only on main, which meant a dependency - # bump had no signal at all and nothing could say whether it was safe to merge. build: runs-on: ubuntu-latest + outputs: + version: ${{ steps.version.outputs.version }} steps: - name: Checkout uses: actions/checkout@v7 - - - name: Set up Python - uses: actions/setup-python@v7 with: - python-version: "3.15" - cache: pip - cache-dependency-path: requirements.txt + # themes/hextra is the tannevaled/hextra fork, pinned to a release tag. + submodules: recursive + # The whole history: each page's date comes from git. + fetch-depth: 0 + + - name: Install Hugo ${{ env.HUGO_VERSION }} + run: | + curl -fsSL -o /tmp/hugo.tar.gz \ + "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_${HUGO_VERSION}_linux-amd64.tar.gz" + echo "${HUGO_SHA256} /tmp/hugo.tar.gz" | sha256sum -c - + sudo tar -xzf /tmp/hugo.tar.gz -C /usr/local/bin hugo + hugo version + + - name: Version + id: version + run: | + documented=$(hugo config --format json | jq -r '.params.docs.version') + if [ "${documented}" = main ]; then + version=main + else + version=$(printf '%s\n' "${documented}" | sed -nE 's/^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/\1.\2/p') + fi + if [ -z "${version}" ]; then + echo "::error::params.docs.version in hugo.yaml is \"${documented}\", not vMAJOR.MINOR.PATCH or main" + exit 1 + fi + echo "version=${version}" >> "$GITHUB_OUTPUT" + echo "documented ${documented}: documentation version ${version}" + + # --panicOnWarning: a relref to a page that is not there, a deprecated + # setting or a template warning fails the build rather than scrolling by. + - name: Build + env: + HUGO_ENVIRONMENT: production + run: >- + hugo --gc --minify --panicOnWarning --printPathWarnings + --baseURL "${DOCS_URL}/${{ steps.version.outputs.version }}/" - - name: Install MkDocs Material + mike + - name: Lay out the site for the link check run: | - pip install --upgrade pip - pip install -r requirements.txt + mkdir -p _check/docs + cp -R public "_check/docs/${{ steps.version.outputs.version }}" - # --strict turns a broken link or an unknown config key into a failure - # rather than a warning nobody reads. - - name: Build the site (strict) - run: mkdocs build --strict + - name: Check links + uses: lycheeverse/lychee-action@v2 + with: + args: >- + --offline --no-progress --include-fragments + --index-files index.html + --root-dir ${{ github.workspace }}/_check + '_check/docs/**/*.html' + fail: true + + - uses: actions/upload-artifact@v7 + with: + name: site + path: public + retention-days: 7 deploy: - # Only main publishes. A pull request stops after build above: it has no - # business pushing to gh-pages, and `permissions: contents: write` is not - # granted to a fork's PR anyway. - if: github.event_name == 'push' || github.event_name == 'workflow_dispatch' + if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main' needs: build - # Two deploys must never run at once: `mike deploy --push` pushes gh-pages, - # and a second job doing the same is rejected outright -- - # - # ! [rejected] gh-pages -> gh-pages (fetch first) - # - # cancel-in-progress stays FALSE deliberately: killing a publish half way - # through is worse than making it wait, and the queued run then fetches the - # gh-pages the previous one just wrote. + # Never two deploys at once: both would push gh-pages and the second would + # be rejected. cancel-in-progress stays false — killing a publish half way + # through is worse than making it wait. concurrency: group: gh-pages-deploy cancel-in-progress: false @@ -61,32 +107,54 @@ jobs: permissions: contents: write steps: - - name: Checkout - uses: actions/checkout@v7 + - uses: actions/checkout@v7 with: + path: gh-pages fetch-depth: 0 - - name: Set up Python - uses: actions/setup-python@v7 + - name: Switch to gh-pages + working-directory: gh-pages + run: | + if git ls-remote --exit-code --heads origin gh-pages >/dev/null; then + git fetch -q origin gh-pages + git checkout -q -B gh-pages FETCH_HEAD + else + echo "no gh-pages branch yet: starting one" + git checkout -q --orphan gh-pages + git rm -rqf . + git clean -fdxq + fi + + - uses: actions/download-artifact@v8 with: - python-version: "3.15" + name: site + path: site - - name: Install MkDocs Material + mike + # Only the version being built is replaced; every other version stays as + # it is, and /docs/latest/ follows the newest. + - name: Publish ${{ needs.build.outputs.version }} + working-directory: gh-pages run: | - pip install --upgrade pip - pip install -r requirements.txt + version="${{ needs.build.outputs.version }}" + rm -rf "docs/${version}" + mkdir -p "docs/${version}" + cp -R ../site/. "docs/${version}/" + newest=$(ls docs | grep -E '^[0-9]+\.[0-9]+$' | sort -t. -k1,1n -k2,2n | tail -1 || true) + if [ -n "${newest}" ]; then + rm -rf docs/latest + cp -R "docs/${newest}" docs/latest + fi + touch .nojekyll - - name: Configure git for mike + - name: Push gh-pages + working-directory: gh-pages run: | - git config user.name "github-actions[bot]" + git config user.name "github-actions[bot]" git config user.email "41898282+github-actions[bot]@users.noreply.github.com" - - # mike publishes versioned docs to the gh-pages branch; GitHub Pages serves - # that branch at https://go-ruby-yaml.github.io/docs/. The version label - # tracks main as "0.1" aliased "latest"; tag-driven versions can be added - # later. /docs/ redirects to the default ("latest"). - - name: Deploy versioned docs - run: | - git fetch origin gh-pages --depth=1 || true - mike deploy --push --update-aliases 0.1 latest - mike set-default --push latest + git add -A + if git diff --cached --quiet; then + echo "nothing changed" + exit 0 + fi + git commit -q -m "Deployed ${GITHUB_SHA::7} to ${{ needs.build.outputs.version }} with Hugo ${HUGO_VERSION}" + git push origin HEAD:gh-pages diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000..966ed98 --- /dev/null +++ b/.gitmodules @@ -0,0 +1,3 @@ +[submodule "themes/hextra"] + path = themes/hextra + url = https://github.com/tannevaled/hextra.git diff --git a/README.md b/README.md index 20db717..6c47d1d 100644 --- a/README.md +++ b/README.md @@ -3,8 +3,7 @@ # go-ruby-yaml/docs Versioned documentation for [go-ruby-yaml](https://github.com/go-ruby-yaml), -built with [MkDocs Material](https://squidfunk.github.io/mkdocs-material/) and -versioned with [mike](https://github.com/jimporter/mike). Published to the +built with [Hugo](https://gohugo.io/) and this fleet's [Hextra fork](https://github.com/tannevaled/hextra) — upstream Hextra plus the opt-in features the fleet's sites use. Published to the `gh-pages` branch and served at . The organization landing page ([go-ruby-yaml.github.io](https://go-ruby-yaml.github.io)) @@ -13,15 +12,18 @@ links here. ## Local preview ```bash -python -m venv .venv && . .venv/bin/activate -pip install -r requirements.txt -mkdocs serve # http://localhost:8000 (current sources) -mike serve # preview the versioned site +git submodule update --init --recursive # themes/hextra, pinned at a release tag +hugo server # http://localhost:1313 ``` ## Releasing a new docs version -```bash -mike deploy --push --update-aliases latest -mike set-default --push latest -``` +Each documented version is its own build under `/docs//`, and +`/docs/latest/` follows the newest — which is what `mike` did before. The version +comes from `params.docs.version` in `hugo.yaml`: set it to the release the pages +describe (`v0.16.0` → `/docs/0.16/`), or leave it at `main` while no release is +tagged. The `docs` workflow reads it, builds with that `--baseURL`, and replaces +**only** that version's path. + +⛔ The build runs with `--panicOnWarning`, so a link to a page that is not there +fails the lane instead of 404ing for a reader. diff --git a/docs/index.md b/content/en/_index.md similarity index 61% rename from docs/index.md rename to content/en/_index.md index b2f283b..4755eff 100644 --- a/docs/index.md +++ b/content/en/_index.md @@ -1,4 +1,9 @@ -# go-ruby-yaml documentation +--- +title: "Home" +weight: 10 +--- + +# go-ruby-yaml documentation {#go-ruby-yaml-documentation} **Ruby's Psych-compatible YAML emitter and loader in pure Go — MRI-compatible, no cgo.** @@ -14,10 +19,13 @@ by `rbgo` as a native module — just like [go-ruby-erb](https://github.com/go-ruby-erb). The dependency runs the other way: this library has **no dependency on the Ruby runtime**. -!!! success "Status: emitter + loader complete — Psych byte-exact, yaml-test-suite conformant" - Faithful port of Ruby's Psych: **`Dump`** emitter and **`Load`** / **`SafeLoad`** loader, with **anchors and aliases**, the **`!ruby/object:`** Ruby tags, **`Symbol` / `Time` / `Range` / bignum** scalars, and both **block and flow** styles. The loader passes the full [yaml-test-suite](https://github.com/yaml/yaml-test-suite) accept/reject axis — **402/402 (accept 308/308 + reject 94/94), 0 panics, 0 known gaps** — and is validated by a **differential oracle** against the system `ruby` / Psych — emitted YAML and loaded values compared byte-for-byte — at 100% coverage, `gofmt` + `go vet` clean, CI green across the six 64-bit Go targets and three OSes. +{{< callout type="info" >}} +**Status: emitter + loader complete — Psych byte-exact, yaml-test-suite conformant** + +Faithful port of Ruby's Psych: **`Dump`** emitter and **`Load`** / **`SafeLoad`** loader, with **anchors and aliases**, the **`!ruby/object:`** Ruby tags, **`Symbol` / `Time` / `Range` / bignum** scalars, and both **block and flow** styles. The loader passes the full [yaml-test-suite](https://github.com/yaml/yaml-test-suite) accept/reject axis — **402/402 (accept 308/308 + reject 94/94), 0 panics, 0 known gaps** — and is validated by a **differential oracle** against the system `ruby` / Psych — emitted YAML and loaded values compared byte-for-byte — at 100% coverage, `gofmt` + `go vet` clean, CI green across the six 64-bit Go targets and three OSes. +{{< /callout >}} -## Quick taste +## Quick taste {#quick-taste} ```go s, _ := yaml.Dump(map[string]any{"a": 1, "b": []any{2, 3}}) @@ -27,7 +35,7 @@ v, _ := yaml.Load("--- &a [1, 2]\n*a\n") // shared via alias v, _ = yaml.SafeLoad("--- !ruby/object:Foo {}") // refused: error ``` -## Repositories +## Repositories {#repositories} | Repo | What it is | | --- | --- | @@ -36,7 +44,7 @@ v, _ = yaml.SafeLoad("--- !ruby/object:Foo {}") // refused: error | [`go-ruby-yaml.github.io`](https://github.com/go-ruby-yaml/go-ruby-yaml.github.io) | the organization landing page (Hugo) | | [`brand`](https://github.com/go-ruby-yaml/brand) | logo and brand assets | -## Principles +## Principles {#principles} - **Pure Go, `CGO_ENABLED=0`** — trivial cross-compilation, a single static binary, no C toolchain. @@ -47,11 +55,11 @@ v, _ = yaml.SafeLoad("--- !ruby/object:Foo {}") // refused: error - **100% test coverage** is the target, enforced as a CI gate, across 6 arches and 3 OSes. -## Where to go next +## Where to go next {#where-to-go-next} -- [Why pure Go](why.md) — why this slice of Ruby is deterministic enough to live +- [Why pure Go]({{< relref "why.md" >}}) — why this slice of Ruby is deterministic enough to live as a standalone, interpreter-independent Go library. -- [Usage & API](api.md) — the public surface and worked examples. -- [Roadmap](roadmap.md) — what is done and what is downstream by design. +- [Usage & API]({{< relref "api.md" >}}) — the public surface and worked examples. +- [Roadmap]({{< relref "roadmap.md" >}}) — what is done and what is downstream by design. Source lives at [github.com/go-ruby-yaml/yaml](https://github.com/go-ruby-yaml/yaml). diff --git a/docs/api.md b/content/en/api.md similarity index 82% rename from docs/api.md rename to content/en/api.md index b910c21..9f7d4f9 100644 --- a/docs/api.md +++ b/content/en/api.md @@ -1,18 +1,26 @@ -# Usage & API +--- +title: "Usage & API" +weight: 30 +--- + +# Usage & API {#usage-api} The public API lives at the module root (`github.com/go-ruby-yaml/yaml`). It is **Ruby-shaped but Go-idiomatic**: `Dump` / `Load` mirror Psych's `Psych.dump` / `Psych.load`, while the surface follows Go conventions — an explicit `error`, value types, no global state. -!!! success "Status: implemented" - The library is built and importable as `github.com/go-ruby-yaml/yaml`, bound into - `rbgo` as a native module; see [Roadmap](roadmap.md). +{{< callout type="info" >}} +**Status: implemented** + +The library is built and importable as `github.com/go-ruby-yaml/yaml`, bound into +`rbgo` as a native module; see [Roadmap]({{< relref "roadmap.md" >}}). +{{< /callout >}} -## Install +## Install {#install} ```sh go get github.com/go-ruby-yaml/yaml ``` -## Worked example +## Worked example {#worked-example} ```go s, _ := yaml.Dump(map[string]any{"a": 1, "b": []any{2, 3}}) @@ -22,7 +30,7 @@ v, _ := yaml.Load("--- &a [1, 2]\n*a\n") // shared via alias v, _ = yaml.SafeLoad("--- !ruby/object:Foo {}") // refused: error ``` -## Shape +## Shape {#shape} ```go // Dump emits Psych-compatible YAML for a Ruby value graph. @@ -36,7 +44,7 @@ func Load(s string) (Value, error) func SafeLoad(s string) (Value, error) ``` -## Conformance +## Conformance {#conformance} The loader is validated against the upstream [yaml-test-suite](https://github.com/yaml/yaml-test-suite) on its @@ -52,7 +60,7 @@ compares the results **byte-for-byte** — not approximated from memory. The ora tests skip themselves where `ruby` is not on `PATH` (e.g. the qemu arch lanes), so the cross-arch builds still validate the library. -## Relationship to Ruby +## Relationship to Ruby {#relationship-to-ruby} `go-ruby-yaml/yaml` is **standalone and reusable**, and is the backend bound into [go-embedded-ruby](https://github.com/go-embedded-ruby/ruby) by `rbgo` as a diff --git a/docs/contributing.md b/content/en/contributing.md similarity index 87% rename from docs/contributing.md rename to content/en/contributing.md index 0d0e111..4dee666 100644 --- a/docs/contributing.md +++ b/content/en/contributing.md @@ -1,10 +1,15 @@ -# Contributing +--- +title: "Contributing" +weight: 60 +--- + +# Contributing {#contributing} Contributions are welcome. `go-ruby-yaml/yaml` is built to a small set of non-negotiable rules — they are what keep it pure-Go, correct, and MRI-compatible. Please read these before opening a pull request. -## Hard rules +## Hard rules {#hard-rules} - **Build from source — no vendoring.** Everything compiles from source. Being able to compile from source is a guarantee of independence. @@ -22,7 +27,7 @@ these before opening a pull request. deterministic core extracted from rbgo's internals. Anything that needs a live Ruby binding belongs in the consumer, not here. -## Workflow +## Workflow {#workflow} 1. Pick or open an issue describing the change. 2. Work test-first: add the differential / unit tests, then make them pass. @@ -36,10 +41,10 @@ these before opening a pull request. 4. Open a PR in English, referencing the issue. -## Where things live +## Where things live {#where-things-live} The library is in [`github.com/go-ruby-yaml/yaml`](https://github.com/go-ruby-yaml/yaml). This documentation site is in [`github.com/go-ruby-yaml/docs`](https://github.com/go-ruby-yaml/docs). Start from the -[Usage & API](api.md) page and the [Roadmap](roadmap.md) to find the right place +[Usage & API]({{< relref "api.md" >}}) page and the [Roadmap]({{< relref "roadmap.md" >}}) to find the right place for your change. diff --git a/docs/performance.md b/content/en/performance.md similarity index 71% rename from docs/performance.md rename to content/en/performance.md index 5136cb5..f662cd2 100644 --- a/docs/performance.md +++ b/content/en/performance.md @@ -1,11 +1,16 @@ -# Performance +--- +title: "Performance" +weight: 50 +--- + +# Performance {#performance} `go-ruby-yaml/yaml` is the pure-Go library that [`rbgo`](https://github.com/go-embedded-ruby/ruby) binds for Ruby's `yaml`. This page records a **comparative benchmark** of that module against the reference Ruby runtimes, part of the ecosystem-wide per-module parity suite. -## What is measured +## What is measured {#what-is-measured} The **same** Ruby script — `YAML.dump` + `YAML.load` round-trip of a representative config structure — is run under every runtime. `rbgo`'s number reflects **this pure-Go library doing the work**; every other column is @@ -24,7 +29,7 @@ before timing. (`yaml.rb` + `run.sh`). Reproduce: `RBGO=./rbgo TRUFFLE=truffleruby bash bench/modules/run.sh 5`. -## Result (best of 5, ms) +## Result (best of 5, ms) {#result-best-of-5-ms} | Runtime | time | vs MRI | | --- | ---: | ---: | @@ -36,15 +41,18 @@ before timing. rbgo runs on **go-ruby-yaml** and is **~4x faster than MRI** here (0.23x). MRI's YAML round-trip is comparatively heavy; the compiled pure-Go dump/load wins clearly. TruffleRuby pays heavy cold warm-up on this row (3370 ms). -!!! note "Honest framing" - JRuby and TruffleRuby are timed **cold, single-shot**, so they carry JVM / - Graal startup on every run — read them as one-shot `ruby file.rb` costs, the - same way `rbgo` and MRI are measured, not as steady-state JIT numbers. Rows - that complete in well under ~200 ms carry the most relative noise; treat - their ratios as order-of-magnitude. These are real measured numbers from the - 2026-06-29 run — nothing is cherry-picked. +{{< callout type="info" >}} +**Honest framing** + +JRuby and TruffleRuby are timed **cold, single-shot**, so they carry JVM / +Graal startup on every run — read them as one-shot `ruby file.rb` costs, the +same way `rbgo` and MRI are measured, not as steady-state JIT numbers. Rows +that complete in well under ~200 ms carry the most relative noise; treat +their ratios as order-of-magnitude. These are real measured numbers from the +2026-06-29 run — nothing is cherry-picked. +{{< /callout >}} -## Library-level benchmark (Go API vs runtimes) — 2026-07-03 +## Library-level benchmark (Go API vs runtimes) — 2026-07-03 {#library-level-benchmark-go-api-vs-runtimes-2026-07-03} This section measures the **pure-Go library directly, through its Go API** — not the `rbgo` interpreter path recorded above. It isolates the library primitive @@ -71,7 +79,7 @@ JRuby / TruffleRuby) before any timing. Interpreter start-up is outside the timed region, so these are operation costs, not `ruby file.rb` process costs. -#### dump-config +#### dump-config {#dump-config} | Runtime | ns/op | vs MRI | | --- | ---: | ---: | @@ -81,7 +89,7 @@ JRuby / TruffleRuby) before any timing. | JRuby | 32377.5 | 0.60× | | TruffleRuby | 145228.5 | 2.68× | -#### load-config +#### load-config {#load-config} | Runtime | ns/op | vs MRI | | --- | ---: | ---: | @@ -103,20 +111,26 @@ runtime's output was verified byte-identical to MRI before timing — the anchor round-trip exactly. TruffleRuby is a **cold-JIT outlier** on these short loops (slower than plain MRI); read its column as order-of-magnitude, not steady state. -!!! note "Reproduce" - The harness is committed under - [`benchmarks/`](https://github.com/go-ruby-yaml/docs/tree/main/benchmarks): - a self-contained Go driver (`go/`, pins the published library via - `go.mod`), the equivalent `ruby/yaml.rb` workload, and `run.sh`. Run - `bash benchmarks/run.sh`; env `OUTER`/`WARM` tune the pass budget and - `RUBY`/`JRUBY`/`TRUFFLERUBY` select the runtime binaries. - -!!! warning "Warm-up budget & noise — honest framing" - Numbers reflect a **fixed warm-process budget** (3 warm-up + 25 timed passes - in one process). The JVM/GraalVM JITs (JRuby, TruffleRuby) may need a larger - warm-up to reach steady state, so their columns can **understate** peak - throughput — most visibly TruffleRuby, whose cold Graal JIT lands slower than - MRI on these short loops. Every number here is a **real measured value** from - the dated run above — nothing is fabricated, estimated, or cherry-picked. The - go-ruby column is the pure-Go library; every other column is that - interpreter's own Psych stdlib doing the equivalent work. +{{< callout type="info" >}} +**Reproduce** + +The harness is committed under +[`benchmarks/`](https://github.com/go-ruby-yaml/docs/tree/main/benchmarks): +a self-contained Go driver (`go/`, pins the published library via +`go.mod`), the equivalent `ruby/yaml.rb` workload, and `run.sh`. Run +`bash benchmarks/run.sh`; env `OUTER`/`WARM` tune the pass budget and +`RUBY`/`JRUBY`/`TRUFFLERUBY` select the runtime binaries. +{{< /callout >}} + +{{< callout type="warning" >}} +**Warm-up budget & noise — honest framing** + +Numbers reflect a **fixed warm-process budget** (3 warm-up + 25 timed passes +in one process). The JVM/GraalVM JITs (JRuby, TruffleRuby) may need a larger +warm-up to reach steady state, so their columns can **understate** peak +throughput — most visibly TruffleRuby, whose cold Graal JIT lands slower than +MRI on these short loops. Every number here is a **real measured value** from +the dated run above — nothing is fabricated, estimated, or cherry-picked. The +go-ruby column is the pure-Go library; every other column is that +interpreter's own Psych stdlib doing the equivalent work. +{{< /callout >}} diff --git a/docs/roadmap.md b/content/en/roadmap.md similarity index 91% rename from docs/roadmap.md rename to content/en/roadmap.md index f7cbe5e..a75828d 100644 --- a/docs/roadmap.md +++ b/content/en/roadmap.md @@ -1,4 +1,9 @@ -# Roadmap +--- +title: "Roadmap" +weight: 40 +--- + +# Roadmap {#roadmap} `go-ruby-yaml/yaml` is grown **test-first**, each capability differential-tested against MRI rather than built in isolation. Ruby's psych yaml — the @@ -15,7 +20,7 @@ deterministic, interpreter-independent slice extracted from rbgo's internals — | yaml-test-suite conformance | The loader passes the full upstream [yaml-test-suite](https://github.com/yaml/yaml-test-suite) accept/reject axis — **402/402**: accept 308/308 well-formed documents load, reject 94/94 ill-formed inputs are rejected (0 panics, 0 known gaps), held by a regression ratchet. | **Done** | | Differential oracle & coverage | A wide value corpus dumped and loaded both here and by the system `ruby`/Psych, compared byte-for-byte; 100% coverage, gofmt + go vet clean, green across all six 64-bit Go arches and three OSes. | **Done** | -## Documented out-of-scope boundaries +## Documented out-of-scope boundaries {#documented-out-of-scope-boundaries} These are **deliberate**, recorded so the module's surface is unambiguous: @@ -29,5 +34,5 @@ These are **deliberate**, recorded so the module's surface is unambiguous: - **Standalone & reusable.** The module has no dependency on the Ruby runtime; the dependency runs the other way. -See [Usage & API](api.md) for the surface and [Why pure Go](why.md) for the +See [Usage & API]({{< relref "api.md" >}}) for the surface and [Why pure Go]({{< relref "why.md" >}}) for the deterministic/interpreter split. diff --git a/docs/why.md b/content/en/why.md similarity index 82% rename from docs/why.md rename to content/en/why.md index 7130703..8278975 100644 --- a/docs/why.md +++ b/content/en/why.md @@ -1,4 +1,9 @@ -# Why pure Go +--- +title: "Why pure Go" +weight: 20 +--- + +# Why pure Go {#why-pure-go} `go-ruby-yaml/yaml` reimplements Ruby's Psych YAML in **pure Go, with cgo disabled**. The slice of Ruby it covers is **deterministic and interpreter-independent**: given @@ -6,7 +11,7 @@ its inputs, the result is a pure function of those inputs — no live binding, n evaluation of arbitrary Ruby. That is exactly the part that can — and should — live as a standalone Go library, separate from the interpreter. -## Extracted from rbgo, reusable by anyone +## Extracted from rbgo, reusable by anyone {#extracted-from-rbgo-reusable-by-anyone} This library began life inside [go-embedded-ruby](https://github.com/go-embedded-ruby/ruby)'s `rbgo` — in the prelude/internals that back the Ruby surface. It has been @@ -20,7 +25,7 @@ This library began life inside [go-embedded-ruby](https://github.com/go-embedded - the behaviour is pinned by a **differential oracle** against the system `ruby`, independent of any one consumer. -## Why pure Go matters here +## Why pure Go matters here {#why-pure-go-matters-here} Because the library is CGO-free and dependency-free, it: @@ -31,5 +36,5 @@ Because the library is CGO-free and dependency-free, it: `PATH`, while the cross-arch lanes (where `ruby` is absent) still validate the library itself. -See [Usage & API](api.md) for the surface and [Roadmap](roadmap.md) for what is +See [Usage & API]({{< relref "api.md" >}}) for the surface and [Roadmap]({{< relref "roadmap.md" >}}) for what is in scope. diff --git a/hugo.yaml b/hugo.yaml new file mode 100644 index 0000000..1950087 --- /dev/null +++ b/hugo.yaml @@ -0,0 +1,87 @@ +# go-ruby-yaml docs documentation — Hugo + Hextra, built like go-plot/docs and +# go-ndarray/docs. +# +# Each documentation version is a separate build under +# https://go-ruby-yaml.github.io/docs//, where is the minor version of the +# code the pages describe, or "main" while no release is tagged. The CI sets it +# through --baseURL, from params.docs.version below; this default is the same +# build. +# +# ⛔ What this replaced was MkDocs Material plus mike, which needed a Python +# toolchain, a requirements.txt and a pip install in CI to render a static site +# for a pure-Go organisation. +baseURL: "https://go-ruby-yaml.github.io/docs/main/" +title: "go-ruby-yaml docs" +# ⛔ No languageCode: deprecated in Hugo 0.158 in favour of locale, and the +# languages block below already says which language this is. The second +# deprecation the pilot build refused, after cascade._target — both inherited +# from copying an older site in this fleet. + +# themes/hextra is the tannevaled/hextra fork, pinned at a release tag as a +# submodule: upstream Hextra plus opt-in features (partial menu items, combos, +# related-sites menu, page subtitle and history, darkreaderLock). +theme: hextra + +defaultContentLanguage: en +defaultContentLanguageInSubdir: false + +languages: + en: + label: "English" + contentDir: content/en + weight: 1 + +enableRobotsTXT: true +# Git history dates every page: "Last updated on" at the foot of each one. +enableGitInfo: true + +markup: + goldmark: + renderer: + unsafe: true + parser: + attribute: + title: true + # ⛔ Block attributes, because every converted heading carries an + # explicit id — "## Heading {#the-mkdocs-slug}". The two slug rules + # disagree: Python-Markdown drops an em dash and collapses the gap it + # leaves into ONE hyphen, goldmark keeps one hyphen per space. An + # anchor is a URL somebody may have saved, so the old spelling is + # kept. Without this setting the braces are printed as text. + block: true + highlight: + noClasses: false + +# ⛔ The content is NOT under content/en/docs. This site is served AT /docs/, +# so a "docs" section would make every page /docs/docs/… . Hextra picks its +# documentation layout from the section being called "docs", so with the +# content at the root the type is cascaded instead. +# ⛔ "target", not "_target": the underscored spelling was deprecated in Hugo +# 0.156 and the fleet's older Hextra sites still carry it, so copying one of +# them is how a converted site arrives with a deprecation. The build runs with +# --panicOnWarning, which is what caught this on the first pilot. +cascade: + - target: + path: "/**" + params: + type: docs + +params: + docs: + version: "main" + description: "A pure-Go reimplementation of Ruby's Psych-compatible YAML emitter and loader, MRI-compatible, no cgo." + navbar: + displayTitle: true + displayLogo: false + theme: + default: system + displayToggle: true + footer: + enable: true + displayCopyright: false + displayPoweredBy: false + page: + width: normal + editURL: + enable: true + base: "https://github.com/go-ruby-yaml/edit/main/content/en" diff --git a/mkdocs.yml b/mkdocs.yml deleted file mode 100644 index ec03c17..0000000 --- a/mkdocs.yml +++ /dev/null @@ -1,61 +0,0 @@ -site_name: go-ruby-yaml docs -site_description: "A pure-Go reimplementation of Ruby's Psych-compatible YAML emitter and loader, MRI-compatible, no cgo." -site_url: https://go-ruby-yaml.github.io/docs/ -repo_url: https://github.com/go-ruby-yaml -repo_name: go-ruby-yaml -edit_uri: "" - -theme: - name: material - logo: assets/logo.svg - favicon: assets/logo.svg - features: - - navigation.sections - - navigation.top - - navigation.instant - - content.code.copy - - search.suggest - palette: - # System default (follows the OS preference), then explicit light and dark. - - media: "(prefers-color-scheme)" - toggle: - icon: material/brightness-auto - name: Switch to light mode - - media: "(prefers-color-scheme: light)" - scheme: default - primary: red - toggle: - icon: material/brightness-7 - name: Switch to dark mode - - media: "(prefers-color-scheme: dark)" - scheme: slate - primary: red - toggle: - icon: material/brightness-4 - name: Switch to system preference - -extra: - version: - provider: mike - default: latest - -nav: - - Home: index.md - - Why pure Go: why.md - - Usage & API: api.md - - Roadmap: roadmap.md - - Performance: performance.md - - Contributing: contributing.md - -markdown_extensions: - - admonition - - attr_list - - def_list - - footnotes - - tables - - toc: - permalink: true - - pymdownx.highlight: - anchor_linenums: true - - pymdownx.superfences - - pymdownx.inlinehilite diff --git a/requirements.txt b/requirements.txt deleted file mode 100644 index 34eb296..0000000 --- a/requirements.txt +++ /dev/null @@ -1,2 +0,0 @@ -mkdocs-material==9.7.7 -mike==2.2.0 diff --git a/docs/assets/logo.svg b/static/assets/logo.svg similarity index 100% rename from docs/assets/logo.svg rename to static/assets/logo.svg diff --git a/themes/hextra b/themes/hextra new file mode 160000 index 0000000..1d8daa4 --- /dev/null +++ b/themes/hextra @@ -0,0 +1 @@ +Subproject commit 1d8daa42d0406250fa00b7e803db2ab104a7fcab