[docs] Published pages silently render incomplete — undefined Sphinx roles/directives + suppressed warnings

Summary

The published documentation silently renders with missing content. Several custom MyST roles/directives the pages depend on are not defined in this repository, and the Sphinx config suppresses the warnings that would surface this — so the build is green while the live site drops requirement tables, validator links, compatibility badges, and tag styling.

Evidence (live site)

On https://nvidia.github.io/simready-foundation/latest/capabilities/core/atomic_asset/requirements.html the requirements table is absent — the page ends at "Detailed Requirements" with no requirement rows.

On https://nvidia.github.io/simready-foundation/latest/capabilities/physics_bodies/physics_graspable/requirements/graspable-vector-line.html the metadata table renders empty Validator / Compatibility / Tags fields:

Code: GSP.001
Validator: (empty)
Compatibility: (empty)
Tags: (empty)

(The USD code examples on that page do render — those use standard fenced code blocks.)

Cause

Three custom roles/directives are referenced throughout the docs but have no implementation in this repo:

They are provided only by an optional, internally-imported extension — nv_core/sr_specs/docs/conf.py:45-47:

try:
    import omni.usd_profiles.sphinx.ext  # noqa: F401
    extensions.append("omni.usd_profiles.sphinx.ext")
except ImportError:
    ...

requirements-docs.txt does not install that package, so the public GitHub Pages build runs without it. And the warnings that would catch this are suppressed — conf.py:51-54:

suppress_warnings = [
    "myst.role_unknown",
    "myst.directive_unknown",
]

Net effect: every requirement table (the actual spec content), every validator link, every compatibility badge, and tag styling is dropped from the published site, with no build signal.

Why it matters

This is a large part of why the docs read as incomplete: the pages that are supposed to enumerate the specifications render empty. A reader cannot see the requirement IDs, validator links, or compatibility for any capability on the public site.

Suggested resolution

1. Vendor the three roles/directives into this repo (open-source the omni.usd_profiles.sphinx.ext pieces, or ship minimal fallback implementations that emit a real table/link/badge).
2. Add the providing package to requirements-docs.txt so the public build matches the internal one.
3. Stop suppressing myst.role_unknown / myst.directive_unknown, and run the docs build with -W (warnings-as-errors) in CI so an undefined role fails the build instead of silently emptying a page.

Verified on main @ 2026.04.1, 2026-05-28.

Start with nv_core/sr_specs/docs/conf.py and requirements-docs.txt, then run the documentation build to reproduce the missing roles and suppressed warnings. Trace the three undefined tokens and the public build configuration before choosing an implementation. Done means published pages contain the requirement tables, validator links, compatibility badges, and tag styling, while unknown roles fail the CI build.