Repository navigation
docs: publish a documentation site on GitHub Pages - #812
Merged
Merged
Conversation
behinddwalls
marked this pull request as ready for review
October 8, 2026 01:17
roychying
approved these changes
Oct 8, 2026
behinddwalls
force-pushed
the
preetam/github-pages
branch
from
October 8, 2026 01:29
f0bb768 to
010e031
Compare
## Summary ### Why? SubmitQueue's docs exist only as Markdown in the repo. A public site with a landing page, navigation and search (like cadenceworkflow.io) makes the project easier to discover and the RFCs easier to browse. ### What? - `tool/docsite/`: MkDocs Material config that renders `doc/` in place, so docs are not copied and the nav picks up new RFCs automatically. - Bazelified: MkDocs runs on a hermetic Python 3.13 toolchain with hash-locked deps (`pip.parse` hub `docsite_pip`; the default Python toolchain is unchanged). `//tool/docsite:site_test` runs the strict build, so `make test` and the required CI test job fail on broken links between docs. - `hooks/repo_links.py` points links that leave `doc/` (code, package READMEs, `AGENTS.md`) at GitHub, so `--strict` stays on and still fails on broken links between pages. - `hooks/nav_titles.py` titles the sections Guides and Design (RFCs) and puts Quickstart first. - `doc/index.md` + `overrides/home.html`: landing page with a hero, feature cards and a quickstart snippet; green brand theme with light and dark modes. - `.github/workflows/docs.yml`: builds the site on PRs that touch `doc/**` or `tool/docsite/**`, and deploys to https://uber.github.io/submitqueue/ from `main`. It is not a required check. - `make docs-serve` / `make docs-build` run MkDocs through Bazel; `docs-serve` binds a free localhost port, like the local service containers (`DOCS_PORT=` pins one); `bazel run //tool/docsite:requirements.update` regenerates the lock. Pages is already enabled on the repo (source: GitHub Actions, deploys restricted to `main`), so merging publishes the site. ## Test Plan ✅ `make docs-build` (strict) and `make docs-serve` work through Bazel ✅ `make test`: 133 tests pass, including `//tool/docsite:site_test`; a deliberately broken link makes it fail ✅ `make check-tidy`, `make gazelle` and `make fmt` leave the tree unchanged; zizmor 1.25.2 and actionlint clean on `docs.yml` ✅ Local preview: checked landing page, tabs, sidebar order, links into code, light and dark modes, and an 845px-wide window
behinddwalls
force-pushed
the
preetam/github-pages
branch
from
October 8, 2026 02:19
010e031 to
82c82ae
Compare
behinddwalls
added a commit
that referenced
this pull request
Oct 8, 2026
## Summary ### Why? The documentation site is live at https://uber.github.io/submitqueue/ (#812), but the README links to it only through a badge. ### What? - Add a **Documentation** link under the intro paragraphs. - Open the Documentation section with a sentence pointing at the site; the table of in-repo documents stays. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
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
2 participants
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.
Summary
Why?
SubmitQueue's docs exist only as Markdown in the repo. A public site with a landing page, navigation and search (like cadenceworkflow.io) makes the project easier to discover and the RFCs easier to browse.
What?
tool/docsite/: MkDocs Material config that rendersdoc/in place, so docs are not copied and the nav picks up new RFCs automatically.pip.parsehubdocsite_pip; the default Python toolchain is unchanged).//tool/docsite:site_testruns the strict build, somake testand the required CI test job fail on broken links between docs.hooks/repo_links.pypoints links that leavedoc/(code, package READMEs,AGENTS.md) at GitHub, so--strictstays on and still fails on broken links between pages.hooks/nav_titles.pytitles the sections Guides and Design (RFCs) and puts Quickstart first.doc/index.md+overrides/home.html: landing page with a hero, feature cards and a quickstart snippet; green brand theme with light and dark modes..github/workflows/docs.yml: builds the site on PRs that touchdoc/**ortool/docsite/**, and deploys to https://uber.github.io/submitqueue/ frommain. It is not a required check.make docs-serve/make docs-buildrun MkDocs through Bazel;docs-servebinds a free localhost port, like the local service containers (DOCS_PORT=pins one);bazel run //tool/docsite:requirements.updateregenerates the lock.Pages is already enabled on the repo (source: GitHub Actions, deploys restricted to
main), so merging publishes the site.Screenshots
Test Plan
✅
make docs-build(strict) andmake docs-servework through Bazel✅
make test: 133 tests pass, including//tool/docsite:site_test; a deliberately broken link makes it fail✅
make check-tidy,make gazelleandmake fmtleave the tree unchanged; zizmor 1.25.2 and actionlint clean ondocs.yml✅ Local preview: checked landing page, tabs, sidebar order, links into code, light and dark modes, and an 845px-wide window
🤖 Generated with Claude Code