docs: add Fern documentation scaffolding#249
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #249 +/- ##
=======================================
Coverage 68.46% 68.46%
=======================================
Files 82 82
Lines 4842 4842
=======================================
Hits 3315 3315
Misses 1395 1395
Partials 132 132 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
Greptile SummaryThis PR adds Fern documentation scaffolding for the topograph project — including an NVIDIA-themed
Confidence Score: 4/5Safe to merge after resolving the tag-triggered publish gap and the open prior findings (missing docs artifact, proprietary CSS license). One new P1 (tag-paths filter interaction silently suppresses versioned doc releases) plus two unresolved P1s from prior review rounds keep this below 5.
Important Files Changed
Sequence DiagramsequenceDiagram
participant PR as Pull Request
participant Build as Preview: Build<br/>(pull_request)
participant Artifact as GitHub Artifact<br/>(fern/ + metadata)
participant Comment as Preview: Comment<br/>(workflow_run)
participant Fern as Fern Cloud
PR->>Build: push to docs or fern files
Build->>Build: Save PR metadata
Build->>Artifact: Upload fern/ + preview-metadata/
Artifact-->>Comment: workflow_run completed
Comment->>Artifact: Download fern-preview artifact
Comment->>Fern: fern generate --docs --preview --id HEAD_REF
Fern-->>Comment: Preview URL
Comment->>PR: Post/update preview comment
note over PR, Fern: Publish path (main branch)
PR->>Fern: push to main with docs/** or fern/**
Fern-->>PR: Docs live at topograph.docs.buildwithfern.com
note over PR, Fern: Versioned publish (tag) — broken
PR->>Fern: git push docs/v* tag
note right of Fern: ⚠️ silently skipped if tagged commit<br/>doesn't touch docs/ or fern/
Reviews (2): Last reviewed commit: "docs: fix MDX img tags, instances URL, a..." | Re-trigger Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| - name: Upload fern sources and metadata | ||
| uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2 | ||
| with: | ||
| name: fern-preview | ||
| path: | | ||
| fern/ | ||
| preview-metadata/ | ||
| retention-days: 1 |
There was a problem hiding this comment.
docs/ directory missing from uploaded artifact
The artifact upload includes fern/ and preview-metadata/ but not docs/. The companion comment workflow runs fern generate --docs --preview from ./fern, which reads fern/docs.yml, and that file references path: ../docs/index.yml. Without the docs/ tree in the artifact, the path resolves to a non-existent location and fern generate will fail for every PR preview.
| - name: Upload fern sources and metadata | |
| uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2 | |
| with: | |
| name: fern-preview | |
| path: | | |
| fern/ | |
| preview-metadata/ | |
| retention-days: 1 | |
| - name: Upload fern sources and metadata | |
| uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2 | |
| with: | |
| name: fern-preview | |
| path: | | |
| fern/ | |
| docs/ | |
| preview-metadata/ | |
| retention-days: 1 |
| /*! | ||
| * SPDX-FileCopyrightText: Copyright (c) 2023-2024 NVIDIA CORPORATION & AFFILIATES. All rights reserved. | ||
| * SPDX-License-Identifier: LicenseRef-NvidiaProprietary | ||
| * | ||
| * NVIDIA CORPORATION, its affiliates and licensors retain all intellectual | ||
| * property and proprietary rights in and to this material, related |
There was a problem hiding this comment.
The SPDX identifier LicenseRef-NvidiaProprietary conflicts with the Apache-2.0 license used throughout the rest of this open-source repository. Including a proprietary-licensed file in an Apache-2.0 project may violate the repository's overall license terms and could block downstream users from distributing or modifying the CSS. Please confirm whether this file is cleared for Apache-2.0 relicensing, or update the header accordingly.
| timeout-minutes: 10 | ||
| steps: | ||
| - name: Checkout repository | ||
| uses: actions/checkout@v5 |
There was a problem hiding this comment.
fern-docs-ci.yml and publish-fern-docs.yml use floating tags (actions/checkout@v5, actions/setup-node@v4) while fern-docs-preview-build.yml pins both to full commit SHAs. Floating tags can silently pick up breaking changes or supply-chain attacks. Consider pinning to commit SHAs here for consistency:
| uses: actions/checkout@v5 | |
| uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 |
- Add fern/ scaffold with NVIDIA theme (assets, CSS, components) - Add docs/index.yml navigation covering all provider and engine pages - Fix broken cross-directory and image links in slinky, slurm, infiniband, and netq docs - Add CI workflows: fern check, PR preview comments, and staging publish Signed-off-by: Pete MacKinnon <pmackinnon@nvidia.com>
Signed-off-by: Pete MacKinnon <pmackinnon@nvidia.com>
pdmack
force-pushed
the
docs/fern-scaffolding
branch
from
42f03c4 to
ea2bd3e
Compare
| on: | ||
| push: | ||
| branches: | ||
| - main | ||
| paths: | ||
| - 'docs/**' | ||
| - 'fern/**' | ||
| tags: | ||
| - 'docs/v*' |
There was a problem hiding this comment.
paths filter silently suppresses tag-triggered publishes
In GitHub Actions, the paths filter under push: applies to both branch pushes and tag pushes. When you push a docs/v* tag, GitHub evaluates the filter against the files changed in the commit the tag points to — so if that commit only modified Go source files (no docs/** or fern/**), the workflow never triggers and the versioned publish is silently skipped.
The workflow comment instructs git tag docs/v1.2.0 && git push origin docs/v1.2.0, which will commonly fail to fire this condition. The workflow_dispatch fallback mitigates this, but the documented tag-based release path is unreliable.
The idiomatic fix is to split the tag trigger into a separate workflow or use an if: condition — GitHub doesn't allow two push: keys in one on: block, but you can restructure as:
on:
push:
branches:
- main
paths:
- 'docs/**'
- 'fern/**'
push:
tags:
- 'docs/v*'
workflow_dispatch: {}Or, more practically, move the versioned publish to a dedicated workflow file triggered only by push: tags: 'docs/v*' without a paths filter.
Ports the Fern workflow guide that already exists in NVIDIA/NVSentinel (also a Fern-based docs site), substituting topograph for nvsentinel in paths and preview URLs. Covers: - Source-of-truth rule: docs/ is authoritative, fern/ is site config and theme only - Local preview commands (fern check, fern docs dev) with the correct topograph path prefix for the bound preview URL - CI workflows table: what each of the four existing fern-* workflows does and when it fires - Secret requirement: DOCS_FERN_TOKEN (matches topograph's publish-fern-docs.yml) - Publishing trigger: docs/v* tag push or Actions dispatch Closes a knowledge gap in how to work with the Fern scaffolding added in NVIDIA#249. NVSentinel is used as the template because it is the only NVIDIA OSS Fern-using repo that currently documents its Fern workflow. Signed-off-by: Rob Esker <resker@nvidia.com>
Ports the Fern workflow guide that already exists in NVIDIA/NVSentinel (also a Fern-based docs site), substituting topograph for nvsentinel in paths and preview URLs. Covers: - Source-of-truth rule: docs/ is authoritative, fern/ is site config and theme only - Local preview commands (fern check, fern docs dev) with the correct topograph path prefix for the bound preview URL - CI workflows table: what each of the four existing fern-* workflows does and when it fires - Secret requirement: DOCS_FERN_TOKEN (matches topograph's publish-fern-docs.yml) - Publishing trigger: docs/v* tag push or Actions dispatch Closes a knowledge gap in how to work with the Fern scaffolding added in #249. NVSentinel is used as the template because it is the only NVIDIA OSS Fern-using repo that currently documents its Fern workflow. Signed-off-by: Rob Esker <resker@nvidia.com>
2 participants
Summary
fern/scaffold with NVIDIA theme to publish provider and engine docs via Ferndocs/index.ymlnavigation covering all 10 provider and engine pagesfern check, PR preview comments, continuous staging publish, versioned tag publishslinky.md,slurm.md,infiniband.md, andnetq.mdTest plan
fern checkpasses locally (0 errors)fern docs devlocal preview (runHOST=0.0.0.0 fern docs devand navigate tohttp://<host>:3000/topograph/dev)Fixes #248
🤖 Generated with Claude Code