docs: add spec-first documentation site - #69
Merged
Conversation
Introduce a Hugo + Relearn documentation site for go-swagger/examples, positioned as the spec-first corner of the three sibling doc sites (this repo = spec-first codegen; go-openapi/runtime = untyped/hand-wired; go-openapi/codescan = code-first). - docs/doc-site/: full content catalog — guides (servers, clients & CLI, authentication, streaming, customizing codegen), tutorials (todo-list, client SDK, custom server), and project pages (README, license, contributing, regeneration). - hack/doc-site/hugo/: Hugo config, custom `code` shortcode, layouts, branding themes, and gendoc.go local-preview helper. Downloaded Relearn theme and generated examples.yaml are git-ignored. - .github/workflows/update-doc.yml: build + deploy to GitHub Pages, mirroring go-openapi/runtime's update-doc workflow. - Region markers (snippet:/endsnippet:) added to hand-written specs and glue across the examples, so guide/tutorial pages embed real, committed, regenerated source via the code shortcode. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
The `code` shortcode embeds real example sources via the assets/examples mount, whose source is the repo root (../../..). Those sources live in top-level example dirs (cli/, task-tracker/, todo-list-errors/, …), not under docs/. The sparse-checkout of hack/+docs/ left them absent in CI, so every `code` shortcode failed to resolve its mounted asset even though the build works locally (where the whole repo is present). Drop the sparse-checkout and check out the full tree. Also replace the `args: >` fold scalar on the Hugo action with a single line: per our workflow conventions, fold scalars in `with:` inputs can reach the runner with embedded newlines and break flag parsing. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
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.
Introduce a Hugo + Relearn documentation site for go-swagger/examples, positioned as the spec-first corner of the three sibling doc sites (this repo = spec-first codegen; go-openapi/runtime = untyped/hand-wired; go-openapi/codescan = code-first).
codeshortcode, layouts, branding themes, and gendoc.go local-preview helper. Downloaded Relearn theme and generated examples.yaml are git-ignored.