diff --git a/.claude/skills/nemo-curator-docs/SKILL.md b/.claude/skills/nemo-curator-docs/SKILL.md index 836b860f6c..9dd40f1e2d 100644 --- a/.claude/skills/nemo-curator-docs/SKILL.md +++ b/.claude/skills/nemo-curator-docs/SKILL.md @@ -320,7 +320,12 @@ This is a temporary maneuver — track the change so it gets reverted. ## Library Reference (Autodocs) and the Fern Cross-Ref Bug -`fern/docs.yml` declares a `libraries:` block that pulls Python source from `nemo_curator/` and generates MDX into `fern/product-docs/nemo-curator/Full-Library-Reference/` (gitignored). It runs as `fern docs md generate` in the publish and preview workflows. +`fern/docs.yml` declares two `libraries:` entries that write to the same output folder (`fern/product-docs/nemo-curator/Full-Library-Reference/`, gitignored): + +- **`nemo-curator`** (`input.git`) — used by CI/publish/preview; requires `fern login` or `FERN_TOKEN`. Workflows run `fern docs md generate --library nemo-curator`. +- **`nemo-curator-local`** (`input.path: ../nemo_curator`) — local dev without Fern auth; requires Docker. Run `npm run generate:library:local` from `fern/`. + +For a full API reference locally (424 pages), use `npm run generate:library`. The local Docker parser is beta and currently produces fewer pages — fine for testing the no-auth flow, not a substitute for CI generation. **Known bug in the Fern Python library generator** (filed upstream): the generator emits cross-references that miss the `/nemo/curator` site basepath (links use `/nemo-curator/...` instead of `/nemo/curator/nemo-curator/...`) and tacks on Sphinx-style `#nemo_curator-…` fragments that don't match any rendered anchor. Result: ~540 broken links across the generated API reference. @@ -347,7 +352,7 @@ python3 fern/_fix_broken_links.py | `{{ variable }}` shows literally on site | Not in `DEFAULT_VARIABLES` in `substitute_variables.py` — add it there | | MDX parse error | Replace bare `` with `[text](https://...)`; escape `<` in prose with `<` or backticks | | Old Sphinx URL breaks | Add a `redirects:` entry in `fern/docs.yml` | -| Library reference missing | Run `fern docs md generate` in `fern/` (see `fern/AUTODOCS_GUIDE.md`) | +| Library reference missing | Run `npm run generate:library` in `fern/` (full reference; needs Fern auth). Or `npm run generate:library:local` without auth (Docker; beta, fewer pages). See `fern/AUTODOCS_GUIDE.md`. | | Broken image | Path is relative to the MDX file; check `fern/assets/` or `pages/_images/` exists | ## Key References diff --git a/.github/workflows/fern-docs-preview-comment.yml b/.github/workflows/fern-docs-preview-comment.yml index 6696f51259..8edb194be7 100644 --- a/.github/workflows/fern-docs-preview-comment.yml +++ b/.github/workflows/fern-docs-preview-comment.yml @@ -64,7 +64,7 @@ jobs: env: FERN_TOKEN: ${{ secrets.DOCS_FERN_TOKEN }} working-directory: ./fern - run: fern docs md generate + run: fern docs md generate --library nemo-curator - name: Generate preview URL id: generate-docs diff --git a/.github/workflows/publish-fern-docs.yml b/.github/workflows/publish-fern-docs.yml index bee9cc7d01..3612ba49c2 100644 --- a/.github/workflows/publish-fern-docs.yml +++ b/.github/workflows/publish-fern-docs.yml @@ -54,7 +54,7 @@ jobs: env: FERN_TOKEN: ${{ secrets.DOCS_FERN_TOKEN }} working-directory: ./fern - run: fern docs md generate + run: fern docs md generate --library nemo-curator - name: Publish Docs env: diff --git a/Makefile b/Makefile index 8d8852ee4e..a0deb9aa22 100644 --- a/Makefile +++ b/Makefile @@ -5,7 +5,8 @@ # make docs # local dev server at http://localhost:3000 # make docs-check # validate Fern config + MDX # make docs-login # guided dashboard sign-in + fern login -# make docs-generate-library # regenerate the Python API reference (libraries:) +# make docs-generate-library # regenerate the Python API reference (git; needs auth) +# make docs-generate-library-local # regenerate locally without Fern auth (Docker) # make docs-substitute # substitute {{ variables }} in MDX (CI runs this automatically) # make docs-substitute DOCS_VERSION=26.02 # make docs-preview # build a shared preview URL (needs DOCS_FERN_TOKEN) @@ -14,7 +15,7 @@ # # See fern/README.md for the full authoring guide. -.PHONY: docs docs-check docs-login docs-generate-library docs-substitute \ +.PHONY: docs docs-check docs-login docs-generate-library docs-generate-library-local docs-substitute \ docs-preview docs-publish docs-clean docs-help # Override FERN to pin a CLI version, e.g. `FERN=npx -y fern-api@4.43.1 make docs-check`. @@ -40,7 +41,11 @@ docs-login: docs-generate-library: @echo "Generating Python API reference under $(FERN_DIR)/product-docs/ (requires FERN_TOKEN)..." - cd $(FERN_DIR) && $(FERN) docs md generate + cd $(FERN_DIR) && $(FERN) docs md generate --library nemo-curator + +docs-generate-library-local: + @echo "Generating Python API reference locally under $(FERN_DIR)/product-docs/ (Docker; no Fern auth)..." + cd $(FERN_DIR) && $(FERN) docs md generate --local --library nemo-curator-local docs-substitute: @echo "Substituting {{ variables }} in versions/v$(DOCS_VERSION) MDX..." @@ -67,7 +72,8 @@ docs-help: @echo " docs local dev server (http://localhost:3000)" @echo " docs-check validate Fern config + MDX" @echo " docs-login guided dashboard sign-in + fern login" - @echo " docs-generate-library regenerate Python API reference (libraries:)" + @echo " docs-generate-library regenerate Python API reference via git (needs auth)" + @echo " docs-generate-library-local regenerate locally without Fern auth (Docker)" @echo " docs-substitute run substitute_variables.py on a version tree" @echo " (override version: make docs-substitute DOCS_VERSION=26.02)" @echo " docs-preview build a shared preview URL (needs DOCS_FERN_TOKEN)" diff --git a/fern/AUTODOCS_GUIDE.md b/fern/AUTODOCS_GUIDE.md index 500ac4b805..90995fcc8b 100644 --- a/fern/AUTODOCS_GUIDE.md +++ b/fern/AUTODOCS_GUIDE.md @@ -86,7 +86,13 @@ Notes: Run: ```bash -fern docs md generate +fern docs md generate --library nemo-curator +``` + +For local generation without Fern authentication (requires Docker): + +```bash +fern docs md generate --local --library nemo-curator-local ``` Fern will generate markdown under the output path you configured, for example: diff --git a/fern/README.md b/fern/README.md index 7cf82d971a..f3bec8cee6 100644 --- a/fern/README.md +++ b/fern/README.md @@ -97,6 +97,17 @@ fern generate --docs # static build For prose-only iteration, `fern docs dev` is enough. Library reference (`product-docs/`) is regenerated by Fern on `dev`/`generate` from the `libraries:` block in `docs.yml`. See [`./AUTODOCS_GUIDE.md`](./AUTODOCS_GUIDE.md) for how that works. +### Library reference without Fern login + +CI and deploy previews use the `nemo-curator` library (`input.git`) and require `fern login` or `FERN_TOKEN`. For local iteration on the Python API reference without Fern authentication, use the `nemo-curator-local` entry (`input.path`) with Docker: + +```bash +npm run generate:library:local +# equivalent: fern docs md generate --local --library nemo-curator-local +``` + +Both libraries write to the same output folder (`product-docs/nemo-curator/Full-Library-Reference`), so previews and publish keep working unchanged. Requires Docker (Fern pulls `fernapi/fern-python-library-docs-parser` on first run). + ### Variable substitution CI runs `substitute_variables.py` before `fern generate` so `{{ container_version }}` and other tokens in MDX are replaced. To run locally (from repo root): @@ -208,7 +219,7 @@ PR titles follow Conventional Commits (e.g. `docs(fern): add rollout collection | Symptom | Fix | |---|---| -| `HTTP 403: User does not belong to organization` on library generation | Sign in to https://dashboard.buildwithfern.com first, then re-run `fern login` | +| `HTTP 403: User does not belong to organization` on library generation | Sign in to https://dashboard.buildwithfern.com first, then re-run `fern login`. Or use `npm run generate:library:local` (no Fern auth; requires Docker). | | `Folder not found: ./product-docs/...` in `fern docs dev` | Library generation hasn't run; trigger a `fern docs dev` cycle or check the `libraries:` block in `docs.yml` | | `fern check` YAML error | 2-space indent; `- page:` inside `contents:`; `path:` is relative to the version YAML | | Page 404 in preview | `slug:` missing/duplicated in the same section, or `position:` collision in an auto-discovered folder | diff --git a/fern/docs.yml b/fern/docs.yml index 58c8de7626..4285be0889 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -183,6 +183,12 @@ libraries: output: path: ./product-docs/nemo-curator/Full-Library-Reference lang: python + nemo-curator-local: + input: + path: ../nemo_curator + output: + path: ./product-docs/nemo-curator/Full-Library-Reference + lang: python experimental: mdx-components: diff --git a/fern/fern.config.json b/fern/fern.config.json index aacfdddc82..dbb24afec3 100644 --- a/fern/fern.config.json +++ b/fern/fern.config.json @@ -1,4 +1,4 @@ { "organization": "nvidia", - "version": "5.29.0" + "version": "5.50.4" } diff --git a/fern/package.json b/fern/package.json index 8e0cb55de0..4e0bab3294 100644 --- a/fern/package.json +++ b/fern/package.json @@ -6,7 +6,8 @@ "check": "npx -y fern-api@latest check", "dev": "npx -y fern-api@latest docs dev", "generate": "npx -y fern-api@latest generate --docs", - "generate:library": "npx -y fern-api@latest docs md generate" + "generate:library": "npx -y fern-api@latest docs md generate --library nemo-curator", + "generate:library:local": "npx -y fern-api@latest docs md generate --local --library nemo-curator-local" }, "engines": { "node": ">=20"