Skip to content

[FIX] Split build-docs into validate and publish jobs - #1283

Merged
Saul (nasaul) merged 3 commits into
mainfrom
fix/validate-docs
Oct 13, 2026
Merged

Saul (nasaul) merged 3 commits into
mainfrom
fix/validate-docs

Conversation

@nasaul

@nasaul Saul (nasaul) commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

Why

build-docs publishes whatever make all_docs produces, so broken MDX, a bad docs.json, or an unresolvable ::: docstring reference ships silently. The first two only fail later in the Nixtla/docs deploy, and the last one never fails at all: the section just disappears from the page. Fork PRs also fail outright, because the docs token is minted before any fork check.

What changed

  • New validate-docs job: builds the docs and runs mint validate. It runs for everyone, including forks, with no secrets and read-only access.
  • New publish-docs job: runs only after validation passes and is skipped for forks and dependabot. It publishes the docs and triggers the docs repo workflow.
  • The publish target is picked in one step (docs/production.yml for releases and manual production runs, docs-preview/preview.yml otherwise), which replaces the duplicated deploy and trigger steps.
  • Hardening: workflow expressions are passed through env vars instead of being inlined, and the validate checkout no longer keeps git credentials.
  • to_mdx.py now fails the build when the parser emits <!-- Error ... --> comments. Before, those comments were stripped, so any ::: reference the parser couldn't resolve was silently dropped from the docs.
  • Removed the docs.json nav entry for AutoArima_vs_Prophet, whose notebook was deleted in [FIX] Add missing tutorial for AutoARIMAProphet adapter #1117. mint validate flagged it on this PR.

Same change as Nixtla/neuralforecast#1639.

Validate the Mintlify build with `mint validate` on every PR (forks included,
no secrets), and only publish to docs-preview/docs after validation passes.
mkdocstrings_parser turns failures into HTML comments, which to_mdx.py then
strips, so broken ::: references silently vanished from the docs.
The notebook was removed in #1117 but its navigation entry was kept.
@nasaul
Saul (nasaul) merged commit c70f657 into main Oct 13, 2026
65 of 66 checks passed
@nasaul
Saul (nasaul) deleted the fix/validate-docs branch October 13, 2026 22:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants