docs: bilingual documentation site with automated GitHub Pages deploy - #8
Merged
Conversation
added 3 commits
August 7, 2026 23:24
The site is built with Material for MkDocs and lives in web/, so documentation and code evolve atomically in the same pull request. Content covers the current 0.2.x surface rather than 0.1.0: OnInvalidConfig, the circuit breaker OnStateChange hook, CircuitBreakerWithState, RetryConfig.AttemptTimeout, NewTokenBucketE and the ErrKindCircuitOpen and ErrKindRateLimited kinds. Two figures were corrected against a fresh measurement: the comparative table describes timeout+retry+breaker, which is what the harness actually configures, and the six-middleware chain is reported as 12 allocs against the 4 of a bare client. English is the default locale at the root and Spanish is served under /es/ via mkdocs-static-i18n, with the navigation translated. Both locales are validated by mkdocs build --strict, which the workflow also runs on pull requests so a broken link cannot reach main. The Python toolchain is pinned exactly: MkDocs 2.0 removes the plugin system both plugins depend on and offers no migration path. None of it reaches the Go module, which stays dependency-free.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Publishes the documentation site that has been sitting in local-only state, updated to the current API surface and translated to Spanish.
What is here
The site (
web/) — Material for MkDocs, 12 pages per locale, living in the same repo so docs and code move in the same PR.Content updated to 0.2.x. The pages described the 0.1.0 surface. Now covered:
OnInvalidConfig,CircuitBreakerConfig.OnStateChange,CircuitBreakerWithState,RetryConfig.AttemptTimeout,NewTokenBucketE/ErrInvalidRateLimit, and theErrKindCircuitOpen/ErrKindRateLimitedkinds. A new Observability page documents the invalid-config hook.Two figures corrected. The comparative benchmark table claimed to measure the full six-middleware chain;
benchmarks/bench_test.goonly configures timeout + retry + circuit breaker. And the six-middleware chain is 12 allocs/op against the 4 of a bare client — measured fresh, previously stated as "adds 12 over a bare transport".Bilingual. English at the root, Spanish under
/es/, viamkdocs-static-i18nwith translated navigation. Cross-page links carrying anchors were retargeted to the Spanish slugs.CI (
.github/workflows/docs.yml) — builds with--stricton every PR touchingweb/, deploys to Pages on push tomain. Least-privilege permissions:pages: writeandid-token: writescoped to the deploy job only.Note on dependencies
web/requirements.txtpins exact versions. MkDocs 2.0 removes the plugin system that both mkdocs-material and mkdocs-static-i18n depend on, with no migration path, so an unpinned install breaks the build the day it lands. This is documentation tooling only — the Go module remains dependency-free.Before merging
GitHub Pages must be enabled with Source: GitHub Actions, otherwise the deploy job fails. It is currently not enabled.