docs(fern): nest fern infra under docs/, hoist nightly MDX to docs/ top-level#2291
Open
lbliii wants to merge 8 commits into
Open
docs(fern): nest fern infra under docs/, hoist nightly MDX to docs/ top-level#2291lbliii wants to merge 8 commits into
lbliii wants to merge 8 commits into
Conversation
Backfills two post-scaffold docs/ changes into the nightly Fern tree that the scaffold had not yet captured: * commit cf1d455 (qwen3-omni ASR recipe): adds guides/audio/qwen3-omni-asr.mdx + image, wires it into the Recipes & E2E Examples nav, and adds the matching rows to the Latest Model Support and Recipes & Guides tables plus the Audio Models section in guides/overview.mdx. * commit 76e7407 (embedding + reranker coverage): adds the new model-coverage/embedding/ and model-coverage/reranker/ sections with their NVIDIA and Mistral pages, registers two new sidebar sections in versions/nightly.yml, and adds the two Auto-class rows to the model-coverage overview table. Content and intent preserved verbatim; only sphinx-isms are rewritten to fern-native MDX (cards, accordions, version-agnostic internal links, GitHub blob/main/ URLs in place of {download} roles). The v0.4 frozen tree and latest/v0.4 alias YAMLs are intentionally not touched - this is nightly drift, not a back-port. Signed-off-by: Lawrence Lane <llane@nvidia.com>
Pure tree move + CI path filter and working-directory updates. No content edits, no docs rewrites — every MDX, YAML, and asset is rename-tracked by git so blame and `git log --follow` continue to work unchanged at the new path. Workflows now trigger on `docs/fern/**` (CI / preview) and `docs/**` (publish), and the `working-directory:` keys are repointed at `./docs/fern`. The .gitignore entry for the generated library reference also moves to `docs/fern/product-docs/`. This is the first commit in a multi-step migration toward the "docs/ holds nightly MDX as top-level siblings of docs/fern/" layout. Subsequent commits will (a) replay-then-convert the sphinx MD ↔ converted MDX pairs so each conversion shows up as a single same-directory `.md` → `.mdx` rename diff for review, then (b) re-wire `docs/fern/versions/nightly.yml` to point at the new top-level paths and retire the now-empty `docs/fern/versions/nightly/` tree. Signed-off-by: Lawrence Lane <llane@nvidia.com>
Bulk same-directory extension rename of all 140 Sphinx Markdown source
files into the Fern MDX tree. Three operations bundled:
1. R100 docs/<...>.md → docs/<...>.mdx (140 files; .md extension
replaced with .mdx, byte-identical content). `git log --follow`
on each new path walks straight back through the legacy
Sphinx history.
2. D docs/fern/versions/nightly/pages/<...>.mdx (140 files; the
pre-converted MDX placeholders are deleted — their bodies are
restored at the same docs/<...>.mdx paths in the next commit).
3. R docs/fern/versions/nightly/pages/api-reference/index.mdx →
docs/api-reference/index.mdx (fern-native page; no MD source).
4. D docs/fern/versions/nightly/{automodel_diagram.png, guides/...} —
drop the page-scoped image copies that lived under the old
nightly/pages tree. The originals already exist at
docs/<section>/<image> from the legacy Sphinx tree.
5. M docs/fern/versions/nightly.yml — rewrite every
`path: ./nightly/pages/<X>.mdx` to `path: ../../<X>.mdx` so the
nav references the new top-level location.
The MDX files at this commit contain the original Sphinx-MD body
(unchanged content, just the extension flipped). The next commit
applies the actual Sphinx → Fern MDX conversion as a per-file
content diff. Splitting the rename from the conversion means
`git show HEAD~ -- docs/<file>.mdx` shows the 100% rename, and
`git show HEAD -- docs/<file>.mdx` (in the next commit) shows
exactly what the conversion rewrote — that's the
before-vs-after diff requested for review.
fern check passes.
Signed-off-by: Lawrence Lane <llane@nvidia.com>
Restores the converted Fern-MDX body at every docs/<...>.mdx path. The
diff against the prior commit is the **complete, per-file Sphinx → Fern
conversion** — for any page, `git show HEAD -- docs/<...>.mdx` isolates
exactly what the migration rewrote at that path:
* Replace leading `# H1` heading with Fern frontmatter
(title / description / position).
* MyST directives → Fern-native MDX components:
:::{card} → plain table or `<Cards>` / `<Card>`
:::{dropdown} / :::{note} → `<Accordion>` / `<Note>` / `<Tip>`
{bdg-*}`label` → `<Tag variant="...">label</Tag>`
{download}`text <path>` → absolute GitHub blob URL link
{toctree} → removed (nav lives in nightly.yml)
(label)= MyST anchors → removed
* Cross-version internal links → version-agnostic
(`/get-started/installation`, no `/latest/` or `/nightly/` prefix).
* Cross-repo refs (yaml, source) → absolute GitHub URLs.
* Image refs stay relative (`./image.png`) so they resolve against
the page-scoped copies in docs/<section>/<image>.
Content, ordering, and link targets are preserved — only the
representation changes. fern check passes.
Signed-off-by: Lawrence Lane <llane@nvidia.com>
…/ layout
Updates the human- and agent-facing orientation docs so they describe
the post-migration layout:
docs/ ← nightly MDX (top level)
docs/fern/ ← infra (config, theme, components, frozen v0.4)
Files touched:
* docs/fern/Makefile run-from-here comments
* docs/fern/README.md full layout + versioning + CI section refresh
* docs/fern/components/Tag.tsx comment path
* docs/fern/components/CustomFooter.tsx comment path
* AGENTS.md skill-table one-liner
* skills/README.md skill-table one-liner
* skills/fern-docs/SKILL.md full rewrite: scope rule, add/update/move/remove
ops now target docs/<path>.mdx with
path: ../../<path>.mdx in nightly.yml;
dropped the obsolete latest.yml alias-sync
step (latest now mounts v0.4 only);
cutting-a-version recipe uses rsync from
docs/ into versions/v0.5/pages/.
Signed-off-by: Lawrence Lane <llane@nvidia.com>
lbliii
requested review from
a team,
HuiyingLi,
adil-a,
akoumpa,
athitten,
hemildesai,
jgerh,
pthombre,
snowmanwwg and
zyzhou5
as code owners
Drops four files that only existed for the old Sphinx build and have
no Fern equivalent:
D docs/conf.py (Sphinx config — Fern uses docs.yml)
D docs/autodoc2_docstrings_parser.py (sphinx-autodoc2 plugin — Fern's
`libraries:` block handles autodoc)
D docs/project.json (Sphinx project metadata)
D docs/versions1.json (Sphinx version-switcher dropdown —
Fern reads versions from docs.yml)
`.github/workflows/release-freeze.yml`: the `bump-docs-versions` job
existed solely to bump these three Sphinx files (versions1.json,
project.json, conf.py) on code freeze. With the files gone, the job
has no work to do, so it's removed and replaced with a short comment
pointing at the Fern equivalent (add a new version pin in
docs/fern/docs.yml + docs/fern/versions/*.yml and tag docs/v<X>.<Y>.0).
fern check still passes.
Signed-off-by: Lawrence Lane <llane@nvidia.com>
…fern-to-docs Signed-off-by: Lawrence Lane <llane@nvidia.com> # Conflicts: # docs/model-coverage/llm/meta/llama.md
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.
What does this PR do?
Restructures the docs tree so the nightly MDX content lives at the top level of
docs/(renamed from the legacy Sphinx.mdsources) and the Fern build infrastructure (config, components, theme, frozen v0.4 snapshot) is nested underdocs/fern/— eliminating the root-levelfern/directory while keeping the standard Fern CLI/build intact.Changelog
3e5ff74b): adds the qwen3-omni ASR guide (#2280) and the embedding + reranker model coverage (#1843), with the new sections wired into the nav YAML.3da7cc4c):git mv fern docs/fernwith no content changes (311 file renames, all 100% similarity); CI path filters (fern-docs-ci.yml,publish-fern-docs.yml,fern-docs-preview-build.yml,fern-docs-preview-comment.yml) and.gitignorerepointed atdocs/fern/.f50ec23b): 140 same-directory.md→.mdxrenames (R100 in git's eyes); deletes the pre-converted MDX placeholders underdocs/fern/versions/nightly/pages/; relocates the fern-nativeapi-reference/index.mdxtodocs/api-reference/; rewrites everypath: ./nightly/pages/<X>.mdxinnightly.ymltopath: ../../<X>.mdxso the nav reaches up intodocs/.8ae8b449): restores the previously-converted MDX body at everydocs/<...>.mdxpath. The diff against the prior commit is the per-file before-vs-after view of exactly what the conversion rewrote (frontmatter, MyST directives → Fern components, version-agnostic internal links, GitHub blob URLs for cross-repo refs).066794fc):docs/fern/README.md,docs/fern/Makefile, component comments,AGENTS.md,skills/README.md, andskills/fern-docs/SKILL.mdupdated to describe the newdocs/(nightly content) +docs/fern/(infra + frozen v0.4) layout. Drops the obsoletenightly.yml↔latest.ymlalias-sync step (latest now mounts v0.4 exclusively).fern checkpasses with 0 errors;git log --follow docs/<any>.mdxtraces back through the rename and convert commits into the legacy Sphinx history so per-file blame and history are intact. The new authoring entry point isdocs/<section>/<page>.mdxwithpath: ../../<section>/<page>.mdxindocs/fern/versions/nightly.yml.Before your PR is "Ready for review"
Pre checks:
Additional Information
git show f50ec23b -- docs/<file>.mdxshows the rename,git show 8ae8b449 -- docs/<file>.mdxshows the Sphinx → Fern conversion diff.backup-pre-squashbranch locally) — same final tree, far fewer commits to review.🤖 Generated with Claude Code