Add docs make flow

.github/workflows/docs.yml

@@ -0,0 +1,73 @@
+name: Publish docs
+
+# Build the MkDocs site and deploy it to GitHub Pages.
+# Pages source must be set to "GitHub Actions" (Settings → Pages → Source).
+on:
+  push:
+    branches: [main]
+    # Only rebuild when something that affects the site changes.
+    paths: &doc_paths
+      - "**.md"
+      - "**.ipynb"
+      - "mkdocs.yml"
+      - "docs-requirements.txt"
+      - "cookbooks/**"
+      - "branding/**"
+      - ".github/workflows/docs.yml"
+  # Build (but don't deploy) on PRs so the site is verified before merge.
+  pull_request:
+    paths: *doc_paths
+  # Allow manual runs from the Actions tab.
+  workflow_dispatch:
+
+# Least-privilege token scopes required to deploy to Pages.
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Let a newer run supersede an in-progress one, but never cancel a live deploy.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # needed for git-based "last updated" timestamps
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+          # Our deps file isn't named requirements.txt, so point pip caching at it
+          # explicitly — otherwise setup-python errors with "No file ... matched".
+          cache-dependency-path: docs-requirements.txt
+
+      - name: Install dependencies
+        run: pip install -r docs-requirements.txt
+
+      - name: Build site
+        # Not --strict: the repo has pre-existing broken doc links (e.g. RELEASE.md
+        # → release_notes/v0p1.md). Warnings still appear in the log; fix them and
+        # add --strict back to enforce link integrity on every deploy.
+        run: mkdocs build --site-dir site
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    # Deploy only on main / manual runs — never on pull requests.
+    if: github.event_name != 'pull_request'
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -192,3 +192,8 @@ core.*
 /public/
 /dataset/
 /downloaded_data/
+
+# MkDocs build output
+/site/
+.site/
+.venv-docs/

branding/nvidia.css

@@ -0,0 +1,122 @@
+/* NVIDIA-style theme for the Cosmos docs.
+ *
+ * Signature NVIDIA green (#76b900) on headings, links, and accents.
+ * The top bar stays black on purpose: green-on-black is NVIDIA's iconic
+ * look and keeps header text readable (bright green + white text fails
+ * contrast). To make the bar itself green, set palette.primary: custom in
+ * mkdocs.yml and add `--md-primary-fg-color: #76b900;` below. */
+
+:root {
+  --nv-green: #76b900;        /* NVIDIA signature green */
+  --nv-green-dark: #5c9100;   /* darker — readable on white */
+  --nv-green-bright: #8fd11a; /* brighter — for dark backgrounds */
+
+  /* Accent drives links/hover/active-nav/search highlight in Material. */
+  --md-accent-fg-color: var(--nv-green-dark);
+}
+
+/* ---- Headings in NVIDIA green ---- */
+.md-typeset h1 {
+  color: var(--nv-green-dark);
+  font-weight: 700;
+}
+
+.md-typeset h2 {
+  color: var(--nv-green-dark);
+  font-weight: 600;
+  /* Subtle green rule under section titles. */
+  border-bottom: 2px solid rgba(118, 185, 0, 0.25);
+  padding-bottom: 0.25em;
+}
+
+.md-typeset h3 {
+  color: var(--nv-green);
+  font-weight: 600;
+}
+
+.md-typeset h4,
+.md-typeset h5 {
+  color: var(--nv-green-dark);
+}
+
+/* ---- Links ---- */
+.md-typeset a {
+  color: var(--nv-green-dark);
+}
+.md-typeset a:hover,
+.md-typeset a:focus {
+  color: var(--nv-green);
+}
+
+/* ---- Small accents: code-block focus, table header tint ---- */
+.md-typeset table:not([class]) th {
+  background-color: rgba(118, 185, 0, 0.10);
+}
+
+/* ---- Top-level "tab" navigation in NVIDIA green ---- */
+/* The tab bar on the (black) header. */
+.md-tabs__link {
+  color: var(--nv-green-bright);
+  opacity: 1;
+}
+.md-tabs__link--active {
+  color: #ffffff;
+  font-weight: 700;
+}
+.md-tabs__link:hover {
+  color: #ffffff;
+}
+
+/* Every entry in the left index (all levels) in NVIDIA green. */
+.md-nav--primary .md-nav__link {
+  color: var(--nv-green-dark);
+}
+/* Top level a bit bolder for hierarchy. */
+.md-nav--primary > .md-nav__list > .md-nav__item > .md-nav__link {
+  font-weight: 700;
+}
+/* Active item: brighter + bold so "you are here" stands out. */
+.md-nav--primary .md-nav__link--active {
+  color: var(--nv-green);
+  font-weight: 700;
+}
+
+/* ---- Left sidebar: group / section titles in NVIDIA green ---- */
+.md-nav__title,
+.md-nav__item--section > .md-nav__link,
+.md-nav__item--section > label.md-nav__link {
+  color: var(--nv-green-dark);
+  font-weight: 700;
+}
+
+/* ---- Hide the README's hand-written "Table of Contents" on the site ----
+ * It's redundant with the left-sidebar TOC (toc.integrate). The heading is
+ * kept in README.md so it still renders usefully on GitHub. */
+.md-typeset h2#table-of-contents,
+.md-typeset h2#table-of-contents + ul {
+  display: none;
+}
+
+/* ---- Dark mode: use the brighter green for contrast ---- */
+[data-md-color-scheme="slate"] {
+  --md-accent-fg-color: var(--nv-green-bright);
+}
+[data-md-color-scheme="slate"] .md-typeset h1,
+[data-md-color-scheme="slate"] .md-typeset h2,
+[data-md-color-scheme="slate"] .md-typeset h3,
+[data-md-color-scheme="slate"] .md-typeset h4,
+[data-md-color-scheme="slate"] .md-typeset h5 {
+  color: var(--nv-green-bright);
+}
+[data-md-color-scheme="slate"] .md-typeset a {
+  color: var(--nv-green-bright);
+}
+[data-md-color-scheme="slate"] .md-typeset a:hover {
+  color: #a6e22e;
+}
+[data-md-color-scheme="slate"] .md-nav__title,
+[data-md-color-scheme="slate"] .md-nav__item--section > .md-nav__link,
+[data-md-color-scheme="slate"] .md-nav__item--section > label.md-nav__link,
+[data-md-color-scheme="slate"] .md-nav--primary .md-nav__link {
+  color: var(--nv-green-bright);
+}

docs-requirements.txt

@@ -0,0 +1,6 @@
+# Dependencies for building the Cosmos documentation site (mkdocs.yml).
+# Install with:  pip install -r docs-requirements.txt
+# Versions below are the ones verified to build the site cleanly.
+mkdocs-material~=9.7
+mkdocs-jupyter~=0.26
+mkdocs-same-dir~=0.1

mkdocs.yml

@@ -0,0 +1,121 @@
+# Cosmos documentation site.
+#
+# This uses Material for MkDocs to publish the existing Markdown + notebooks
+# WITHOUT moving any files: the `same-dir` plugin makes the repo root the docs
+# source, so nav entries below point straight at the files where they already
+# live. Preview locally with `mkdocs serve`; publish via GitHub Pages later.
+
+site_name: Cosmos
+site_description: NVIDIA Cosmos — world foundation models for Physical AI
+site_url: https://nvidia.github.io/cosmos/
+
+repo_url: https://github.com/NVIDIA/cosmos
+repo_name: NVIDIA/cosmos
+edit_uri: edit/main/
+
+theme:
+  name: material
+  # NOTE: assets must live in a SUBDIRECTORY. The same-dir plugin drops
+  # non-Markdown files at the repo root, so a root-level logo would 404.
+  logo: branding/cosmos-logo-thumbnail.png
+  favicon: branding/cosmos-logo-thumbnail.png
+  icon:
+    repo: fontawesome/brands/github
+  palette:
+    # Light mode
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: black
+      accent: green
+      toggle:
+        icon: material/weather-night
+        name: Switch to dark mode
+    # Dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: black
+      accent: green
+      toggle:
+        icon: material/weather-sunny
+        name: Switch to light mode
+  features:
+    - navigation.tabs
+    - navigation.sections
+    - navigation.top
+    - navigation.indexes
+    - navigation.footer
+    - toc.follow
+    # Render each page's table of contents INSIDE the left sidebar (Sana-style),
+    # instead of a separate right-hand column. Left = jump index, middle = content.
+    - toc.integrate
+    - search.suggest
+    - search.highlight
+    - content.code.copy
+    - content.action.edit
+
+# docs_dir is the repo root so existing files are published in place (no moves).
+# The `same-dir` plugin is what makes pointing docs_dir at the config dir legal.
+docs_dir: .
+
+extra_css:
+  - branding/nvidia.css
+
+plugins:
+  - same-dir
+  - search
+  - mkdocs-jupyter:
+      include_source: true
+      execute: false
+
+markdown_extensions:
+  - admonition
+  - attr_list
+  - md_in_html
+  - tables
+  - footnotes
+  - toc:
+      permalink: true
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.inlinehilite
+  - pymdownx.superfences
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.details
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+
+# Keep the build limited to documentation: with docs_dir at the repo root,
+# everything else (data files, large assets, configs) is excluded from copying.
+exclude_docs: |
+  /.github/
+  /site/
+  /.venv/
+  /*.parquet
+  /**/*.parquet
+
+nav:
+  - Home: README.md
+  - Benchmarks: inference_benchmarks.md
+  - Cookbooks:
+      - Environment Setup: cookbooks/cosmos3/README.md
+      - Reasoner:
+          - Overview: cookbooks/cosmos3/reasoner/README.md
+          - Run with Cosmos Framework: cookbooks/cosmos3/reasoner/run_with_cosmos_framework.ipynb
+          - Run with vLLM: cookbooks/cosmos3/reasoner/run_with_vllm.ipynb
+          - Run with NIM: cookbooks/cosmos3/reasoner/run_with_nim.ipynb
+      - Generator — Action:
+          - Overview: cookbooks/cosmos3/generator/action/README.md
+          - Run FD with vLLM: cookbooks/cosmos3/generator/action/run_fd_with_vllm.ipynb
+          - Run ID with vLLM: cookbooks/cosmos3/generator/action/run_id_with_vllm.ipynb
+          - Run ID with Cosmos Framework: cookbooks/cosmos3/generator/action/run_id_with_cosmos_framework.ipynb
+          - Run FD with Cosmos Framework: cookbooks/cosmos3/generator/action/run_fd_with_cosmos_framework.ipynb
+          - Run Policy with Cosmos Framework: cookbooks/cosmos3/generator/action/run_policy_with_cosmos_framework.md
+      - Generator — Audiovisual:
+          - Overview: cookbooks/cosmos3/generator/audiovisual/README.md
+          - Run with diffusers: cookbooks/cosmos3/generator/audiovisual/run_with_diffusers.ipynb
+          - Run with Cosmos Framework: cookbooks/cosmos3/generator/audiovisual/run_with_cosmos_framework.ipynb
+          - Run with vLLM Omni: cookbooks/cosmos3/generator/audiovisual/run_with_vllm_omni.ipynb
+  - Contributing: CONTRIBUTING.md
+  - Release Notes: RELEASE.md