Skip to content

docs: add documentation site and shorten README - #198

Merged
FloSch62 merged 1 commit into
mainfrom
docs-site
Nov 7, 2026
Merged

FloSch62 merged 1 commit into
mainfrom
docs-site

Conversation

@FloSch62

@FloSch62 FloSch62 commented Nov 7, 2026

Copy link
Copy Markdown
Member

Summary

Replaces the ~500-line README with a short one and moves the documentation to a GitHub Pages site, styled like the Containerlab Apps docs.

Site (docs-site/, built with Zensical):

  • Home: pitch, install-and-call snippet, architecture diagram, features, install options
  • Get started: quick start (write a lab file, upload, deploy, ping, destroy with curl) and how it works
  • Install: choose a method, systemd service, container, binary, upgrade and remove
  • Guides: use the API, users and sign-in, workspaces, templates, deploy options, shared labs, labs on Kubernetes
  • Reference: full configuration (adds settings missing from the old README, e.g. capture and TRUSTED_PROXIES), security model, Kubernetes internals, REST API
  • ReDoc API reference at /api/; /swagger.json and /swagger.yaml stay at the site root for existing links
  • Containerlab wordmark in the header and hero
  • Live topology diagrams rendered by @containerlab/clab-viewer from docs-site/diagrams/*.clab.yml (the clab fence extension is shared with containerlab-app in tools/clab_docs/)

docs/kubernetes.md is split into a setup guide and an internals reference. The RBAC manifests stay in docs/kubernetes/ and are applied by URL.

Build and publish:

  • task docs previews the site, task docs:build builds it (needs uv). scripts/docs.sh copies the OpenAPI spec and fetches the viewer bundle
  • pages.yml keeps publishing to the gh-pages branch, so Pages settings are unchanged. It now replaces the branch contents on each publish
  • New docs.yml builds the site with --strict on pull requests that touch the docs

Notes

  • The site root becomes the docs home instead of ReDoc; the API reference moves to /api/.

Test plan

  • scripts/docs.sh build passes in strict mode
  • Checked home, quick start, Kubernetes, configuration and API pages in a headless browser, dark and light, desktop and phone widths
  • Docs workflow passes on this PR
  • After merge, Pages publishes and https://srl-labs.github.io/clab-api-server/ shows the new site

Add a Zensical documentation site in docs-site/, styled like the
Containerlab Apps docs, with the containerlab wordmark and live topology
diagrams from @containerlab/clab-viewer.

- Get started, install, guides, and reference pages built from the
  former README, plus a full configuration reference
- Split the Kubernetes doc into a setup guide and an internals reference
- ReDoc API reference at /api/, keeping /swagger.json and /swagger.yaml
  at the site root
- task docs / task docs:build via scripts/docs.sh
- Pages workflow publishes the full site to gh-pages; a new docs
  workflow builds it on pull requests
- README reduced to install, first call, and links to the site
@FloSch62
FloSch62 merged commit 02c01c2 into main Nov 7, 2026
3 checks passed
@FloSch62
FloSch62 deleted the docs-site branch November 7, 2026 10:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant