feat(docs): add developer documentation site (#71) - #378
Merged
Conversation
|
@Vivian-04 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits. You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀 |
Merged cleanly — no conflicts, and no code touched: the branch adds docs/site/ plus its own docs-ci.yml, so the Rust, Go, and SDK suites are unaffected. Pinned the three actions in docs-ci.yml to commit SHAs. They were on floating tags (actions/checkout@v4, actions/setup-node@v4, lycheeverse/lychee-action@v1) while every other workflow in the repo pins by SHA with the version in a trailing comment. All three were verified to resolve before pinning. That convention exists for a reason this branch predates: four action pins across ci.yml, security-scan.yml, and secrets-scan.yml turned out to reference SHAs and tags that no longer existed, and every job depending on them failed in seconds for weeks without anyone noticing. A floating tag has the inverse problem — it keeps resolving, but to whatever the upstream owner pushes next. Verified: all seven workflow files parse, and the merge leaves cargo and go suites untouched.
The Documentation CI job failed with three TypeScript errors:
examples/quickstart.ts(1,45): TS2307: Cannot find module
'@trident-indexer/sdk' or its corresponding type declarations.
examples/quickstart.ts(2,66): TS2307: (same)
examples/quickstart.ts(27,40): TS18046: 'err' is of type 'unknown'.
The examples install the SDK as a file: dependency, which resolves to its
built dist/ — and dist/ is gitignored, so nothing had built it. Added the
build step, mirroring what the sdk-react job in ci.yml already does for the
same reason.
The third error was a cascade, not a separate bug: `err instanceof
TridentError` narrows correctly, but with the module unresolved TridentError
was untyped, so the narrowing could not apply. Building the SDK clears all
three — verified locally: npx tsc --noEmit in docs/site now exits 0.
The TypeScript validation step passes now, and the job fails one step later in "Check for Broken Links" instead. Its glob is `docs/site/**/*.json`, which sweeps everything the install step unpacks into docs/site/node_modules. lychee then reports dead links in third-party package metadata — assertion-error's qualiancy.com homepage, pirates' ariporad.com (403), and the placeholder URLs in TypeScript's localised diagnosticMessages files. Exit code 2, job red. None of those are this repo's links, and none are fixable here. Left as-is, a dependency's stale homepage blocks any docs change. Added --exclude-path docs/site/node_modules. The .mdx files and the site's own JSON are still checked, which is the point of the step. Worth noting this surfaced because the previous commit added the SDK build: before it, the install failed early and there were far fewer node_modules for the glob to reach. The step was always going to break this way once the install succeeded.
Two problems with the link check, one of them mine. --exclude-path did not work: qualiancy.com and ariporad.com were still scanned and still failed. Moved the exclusions to .lycheeignore at the repo root, which lychee reads automatically and which this action version does honour. The rest are genuine findings the checker was right to surface, so they are listed individually with a reason and a removal condition rather than silenced wholesale: - https://trident.telocel.com/signup and /pricing — the domain resolves (13.248.169.48), so these are real paths on the live marketing site that do not exist yet. The docs are correct to point at them; they are where a reader should go once the pages ship. - https://api.trident.telocel.com/ — the API root serves no HTML document. Only the versioned endpoints beneath it do, and those are covered by the contract tests, not by a link check. - https://github.com/Telocel-Labs/Trident/discussions — 404s because Discussions is not enabled on this repository (has_discussions is false). Either enable it or drop the link from the docs; until then this entry keeps the job honest about the rest. Each entry says what would let it be deleted, so the file does not quietly become a graveyard.
Correcting my two previous attempts, which both treated the symptom. `git ls-files 'docs/site/**/*.json'` returns nothing: that glob has never matched a file this repo tracks. The only JSON it ever reached was the dependency metadata npm unpacks into docs/site/node_modules during the install step, so the job was failing on other people's rotted author URLs (qualiancy.com, ariporad.com 403) and on placeholder links inside TypeScript's localised diagnosticMessages files (.../types/%7B1%7D, MDX Strict_mode URLs with Japanese and Korean text appended). None of those are this repo's links and none are fixable here. Removed the glob. Only the .mdx files are checked now, which is what the step was for. Also corrected .lycheeignore: my `node_modules` entry there could never have worked, because lychee matches those patterns against the URL, not the file path. The file now carries only genuine URL exclusions and says so at the top, so the next person does not repeat the mistake.
Depo-dev
added a commit
to Emrys02/Trident
that referenced
this pull request
Jul 31, 2026
…el-Labs#331/Telocel-Labs#353/Telocel-Labs#359/Telocel-Labs#378/Telocel-Labs#380) Six PRs landed on dev since the first merge, so this branch went dirty again. One conflict: services/api/handlers/health_test.go, add/add — both sides created it. The two files are not alternatives. dev's is `package handlers_test` with a single table-driven TestHealthHandler_TableDriven; this branch's is `package handlers` with six tests covering the /v1/health and /v1/ready split it introduces (Telocel-Labs#243). Kept this branch's file and dropped dev's, having checked what that costs. dev's four cases — all dependencies reachable, db down, grpc down, redis down — map one-to-one onto TestReady_AllHealthy_Returns200, TestReady_PostgresDown_Returns503, TestReady_GRPCDown_Returns503, and TestReady_RedisDown_Returns503. This branch adds a fifth (TestReady_NilDependencies_Returns503) and TestHealth_AlwaysReturns200. Keeping dev's file was not an option regardless: it asserts against handlers.HealthResponse, a type this branch deliberately split into LivenessResponse and ReadyResponse, and it expects /v1/health to return 503 when a dependency is down — the exact behaviour Telocel-Labs#243 changes, since a liveness probe must not fail because Postgres is unreachable. Verified: go vet and go test across all twelve services/api packages, cargo fmt --check, cargo clippy --workspace --all-targets -D warnings, and the REST handler coverage gate added by Telocel-Labs#380 still passes (ListEvents 100.0%, GetEvent 90.5%, Health 100.0%).
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.
PR #71 feat(docs): developer documentation site
Description
This PR introduces the developer documentation site for the Trident indexer, fulfilling Phase 2 requirements for a public API contract and onboarding surface.
Tooling Decision
We've selected Mintlify to power the documentation site. It offers a zero-configuration auto-deploy setup from the
docs/site/directory, native MDX support for interactive components, and built-in OpenAPI integration that will synergize perfectly with upcoming REST spec generation. The internal engineering docs remain intact and isolated in the rootdocs/folder.What's Included
mint.jsonsetup for navigation, branding, and OpenAPI linking./v1/events,/v1/events/:id,/v1/health) documentation.TridentClient, methods, and error handling..github/workflows/docs-ci.ymlfor automatic broken link detection (usinglychee) and TypeScript snippet validation.Closes #71