docs: implement publishing pipeline (#617)

[planetf1]

docs: implement publishing pipeline

Note: Replaces #644 — recreated from an upstream branch so that the
docs-preview label can trigger a full deploy to docs/preview for
pipeline validation (fork PRs lack write access to push deployment branches).

Type of PR

• Bug Fix
• New Feature
• Documentation
• Other

Description

• Link to Issue: Fixes docs: implement publishing pipeline #617

Fixes #617

This PR completes the end-to-end documentation publishing pipeline for
Mellea. From a single push to main, the full Mintlify docs site —
hand-authored guides plus generated API reference — is automatically built,
validated, and deployed. Reviewers can now see live docs at the staging
environment without any manual steps.

Live preview: While this PR is open, the pipeline is publishing to
https://ibm-llm-runtime-aaf3a78b.mintlify.app/ via the Mintlify staging
configuration (pointing at docs/preview). This is temporary — once merged,
staging will track main via docs/staging.

See docs/PUBLISHING.md for the full architecture, branch strategy, and local development workflow.

Job summary output: Checks tab → any Docs run → Summary. Example: https://github.com/generative-computing/mellea/actions/runs/23064193854

Example docs job summary output

Changes

• docs-publish.yml — new unified workflow (replaces docs-autogen-pr.yml). Deploys to docs/staging, docs/production, or docs/preview depending on trigger. Soft-fail validation by default; rich job summaries on every run.
• quality.yml — additive only: job summary with pre-commit outcome and test pass/fail counts.
• .pre-commit-config.yaml — MDX validation hook (normal flow) + docstring quality hook (manual-only pending ci: gate doc quality in CI and pre-commit to prevent future degradation #616).
• audit_coverage.py — fix false-positive GHA annotation; remove noisy per-item annotations.
• docs/PUBLISHING.md — design doc: architecture, branch strategy, local dev, Mintlify config.

Dependencies

Both prerequisites have merged:

• docs: complete developer documentation rewrite (#480) #601 — static docs rewrite ✅
• docs: Docs/api pipeline improvements #611 — API docs pipeline ✅

Follow-on

• docs: improve docstrings for API reference (#612) #614 — docstring quality pass; will reduce the 746 issues currently reported in CI.
• ci: gate doc quality in CI and pre-commit to prevent future degradation #616 — enable hard-fail quality gate once docs: improve docstrings for API reference (#612) #614 brings the count to 0.
• docs: pre-release documentation verification pass #645 — pre-release content review pass before tagging the next release.
• Mintlify cutover — once merged and content review (docs: pre-release documentation verification pass #645) is complete:
  point the Mintlify production site at docs/production (populated on the
  next release) and update the staging environment to track docs/staging.
  This is the final step to make the new docs the live public site.

Testing

• Tests added to the respective file if code was changed
• New code has 100% coverage if code as added
• Ensure existing tests and github automation passes (a maintainer will kick off the github automation when the rest of the PR is populated)

Testing plan:

• docs-preview label is already applied — verify Docs workflow builds,
  validates, and deploys to docs/preview successfully.
• Review job summaries on the Docs and Run CI checks (Checks tab above).
• Browse the live preview at https://ibm-llm-runtime-aaf3a78b.mintlify.app/
• Flip strict_validation via workflow_dispatch when ready to test hard failures.

[mergify]

Merge Protections

Your pull request matches the following merge protections and will not be merged until they are valid.

🟢 Enforce conventional commit

Wonderful, this rule succeeded.

Make sure that we follow https://www.conventionalcommits.org/en/v1.0.0/

• title ~= ^(fix|feat|docs|style|refactor|perf|test|build|ci|chore|revert|release)(?:\(.+\))?:

[planetf1]

Publishing is now running.

This PR is tagged with docs-preview. This causes the build process to publish to the docs/preview branch (there are no checks preventing clashes - this is just an occasional exception to help with testing)

Mintlify has temporarily been updated to publish automatically from this docs/preview / to https://ibm-llm-runtime-aaf3a78b.mintlify.app/

Normally a PR will just do validation, but not publish

@HendrikStrobelt you may want to take a look. Focus is on the process - and only content that fundamentally breaks the process. General content changes can be in other PRs. Issues already open in a few areas, docstrings, and a catchup of changes made over last 1-2 weeks.

I have more things to fix/consolidate in the pipeline, check reported soft-errors etc - just a heads up that we have the core of the end-end process

[psschwei]

In general, this all makes sense to me and I'm on board.
will hold off on approval in case others want to chime in

[planetf1]

Added a summary

For example at https://github.com/generative-computing/mellea/actions/runs/23063294187?pr=646

[planetf1]

#614 should address many (not all) of the issues reported in the current checks.

I suggest we now get this PR reviewed/merged -- and Monday I'll revisit 614 & finish out the discussion on doc string formatting. If that changes the requirements of the parsers here will update then. One step forward.... it's a bit iterative - but we'll converge!

[planetf1]

Note the job summary I mentioned above had truncated output. That's been fixed ( see https://github.com/generative-computing/mellea/actions/runs/23063949076?pr=646 )

There may be improvements to the reports - but can defer to later.

[psschwei]

LGTM

[planetf1]

Updated mintlify so we are now publishing to the staging branch and url from merges to main