Misc docs rendering fixes

.github/workflows/docs.yml

@@ -28,6 +28,7 @@ jobs:
       - name: 'Build docs'
         env:
           NVTE_DOCS_DISABLE_PUBLIC_FEATURES: '1'
+          NVTE_DOCS_SWITCHER_JSON_URL: 'versions1.json'
         run: | # SPHINXOPTS="-W" errors out on warnings
           doxygen docs/Doxyfile
           cd docs

docs/_static/css/diagram-colors.css

@@ -70,6 +70,27 @@
   font-size: 15px;
   font-weight: 600;
   text-anchor: middle;
+  fill: #212121;
+}
+
+/* Accent text colors (used together with .text/.small-text/.section-title) */
+.accent-blue { fill: #1565c0; }
+.accent-red { fill: #c62828; }
+.accent-green { fill: #388e3c; }
+.accent-orange { fill: #f57c00; }
+
+/* Neutral container panels (master_weights_approaches.svg) */
+.panel {
+  fill: #f5f5f5;
+  stroke: #9e9e9e;
+  stroke-width: 1.5;
+}
+
+/* Range bracket lines (fp8_scaling_concept.svg) */
+.range-bracket {
+  stroke: #666;
+  stroke-width: 1.5;
+  fill: none;
 }
 
 /* Arrows */
@@ -132,3 +153,129 @@
   stroke-width: 2.5;
 }
 
+/* Dark mode overrides: darken fills and lighten text so diagrams stay
+   legible against the theme's dark background. */
+html[data-theme="dark"] .hp { fill: #3a2f5c; stroke: #b39ddb; }
+html[data-theme="dark"] .fp8 { fill: #4d3c00; stroke: #ffca28; }
+html[data-theme="dark"] .gemm { fill: #663c00; stroke: #ffb74d; }
+html[data-theme="dark"] .quantize { fill: #1b3d1e; stroke: #81c784; }
+html[data-theme="dark"] .amax { fill: #0d3c54; stroke: #4fc3f7; }
+html[data-theme="dark"] .allgather { fill: #0d3c54; stroke: #4fc3f7; }
+html[data-theme="dark"] .box-blue { fill: #10375c; stroke: #64b5f6; }
+html[data-theme="dark"] .box-orange { fill: #5c3a10; stroke: #ffb74d; }
+html[data-theme="dark"] .box-green { fill: #1e4620; stroke: #81c784; }
+html[data-theme="dark"] .layernorm { fill: #10405c; stroke: #4fc3f7; }
+html[data-theme="dark"] .fused { fill: #103c38; stroke: #4db6ac; }
+html[data-theme="dark"] .computation { fill: #2b2b2b; stroke: #9e9e9e; }
+html[data-theme="dark"] .fp32 { fill: #5c1f1f; stroke: #ef9a9a; }
+
+html[data-theme="dark"] .text,
+html[data-theme="dark"] .title {
+  fill: #f5f5f5;
+}
+
+html[data-theme="dark"] .small-text {
+  fill: #bdbdbd;
+}
+
+html[data-theme="dark"] .label {
+  fill: #e0e0e0;
+}
+
+html[data-theme="dark"] .arrow {
+  stroke: #bdbdbd;
+}
+
+/* Text sitting directly on the page background (not inside boxes) */
+html[data-theme="dark"] .section-title,
+html[data-theme="dark"] .section-label,
+html[data-theme="dark"] .column-title,
+html[data-theme="dark"] .dots-text,
+html[data-theme="dark"] .dots-text-small {
+  fill: #e0e0e0;
+}
+
+/* Lighter accents; must come after the .text/.small-text overrides */
+html[data-theme="dark"] .phase-forward,
+html[data-theme="dark"] .accent-blue { fill: #64b5f6; }
+html[data-theme="dark"] .phase-backward,
+html[data-theme="dark"] .accent-red { fill: #ef9a9a; }
+html[data-theme="dark"] .accent-green { fill: #81c784; }
+html[data-theme="dark"] .accent-orange { fill: #ffb74d; }
+
+/* Arrowhead markers use fill attributes, which any CSS rule overrides */
+html[data-theme="dark"] marker polygon {
+  fill: #bdbdbd;
+}
+
+/* Container panels and bracket/axis strokes on the page background */
+html[data-theme="dark"] .panel { fill: #1f1f1f; stroke: #757575; }
+html[data-theme="dark"] .range-bracket { stroke: #bdbdbd; }
+html[data-theme="dark"] .arrow-dashed { stroke: #bdbdbd; }
+html[data-theme="dark"] .axis-line,
+html[data-theme="dark"] .axis,
+html[data-theme="dark"] .tick,
+html[data-theme="dark"] .bwd-bracket { stroke: #bdbdbd; }
+
+/* Text on the page background in bit-layout / axis diagrams */
+html[data-theme="dark"] .format-label,
+html[data-theme="dark"] .value-text,
+html[data-theme="dark"] .tick-label { fill: #f5f5f5; }
+html[data-theme="dark"] .header-text,
+html[data-theme="dark"] .range-label,
+html[data-theme="dark"] .sub-label { fill: #bdbdbd; }
+html[data-theme="dark"] .param-label,
+html[data-theme="dark"] .bracket-label { fill: #e0e0e0; }
+
+/* Flow-diagram box classes (mxfp8/blockwise swizzle-flow diagrams) */
+html[data-theme="dark"] .input-box,
+html[data-theme="dark"] .quantize-box { fill: #3a2f5c; stroke: #b39ddb; }
+html[data-theme="dark"] .quantize-fused-box { fill: #4a3a70; stroke: #b39ddb; }
+html[data-theme="dark"] .mxfp8-box,
+html[data-theme="dark"] .blockwise-box { fill: #10375c; stroke: #64b5f6; }
+html[data-theme="dark"] .fp8-tile { fill: #16496f; stroke: #64b5f6; }
+html[data-theme="dark"] .scale-tile,
+html[data-theme="dark"] .gemm-box { fill: #1e4620; stroke: #81c784; }
+html[data-theme="dark"] .scale-swizzled,
+html[data-theme="dark"] .swizzle-box { fill: #5c3a10; stroke: #ffb74d; }
+html[data-theme="dark"] .comm-box { fill: #4d3c00; stroke: #ffca28; }
+
+/* rht.svg and nvfp4_all_gather.svg boxes */
+html[data-theme="dark"] .input { fill: #10375c; stroke: #64b5f6; }
+html[data-theme="dark"] .grad { fill: #5c1f38; stroke: #f48fb1; }
+html[data-theme="dark"] .rht { fill: #5c3a10; stroke: #ffb74d; }
+html[data-theme="dark"] .output { fill: #1e4620; stroke: #81c784; }
+html[data-theme="dark"] .nvfp4 { fill: #10375c; stroke: #64b5f6; }
+
+/* White backing rects behind "..." glyphs: match the page background */
+html[data-theme="dark"] .diagram-bg { fill: #121212; }
+html[data-theme="dark"] .tensor-outline { stroke: #9e9e9e; }
+
+/* Inter-frame connector segments drawn on the page background */
+html[data-theme="dark"] .connector-ext { stroke: #bdbdbd; }
+
+/* Ellipsis glyphs that sit on cells that stay light in dark mode */
+html[data-theme="dark"] .on-light-bg { fill: #212121; }
+
+/* cpu_offloading diagrams (classes unique to those four SVGs) */
+html[data-theme="dark"] .layer-box { fill: #2b2b2b; stroke: #9e9e9e; }
+html[data-theme="dark"] .layer-text { fill: #e0e0e0; }
+html[data-theme="dark"] .tensor-box { fill: #10375c; stroke: #64b5f6; }
+html[data-theme="dark"] .tensor-text { fill: #90caf9; }
+html[data-theme="dark"] .fwd-block { fill: #2e4a63; stroke: #7ba7cc; }
+html[data-theme="dark"] .bwd-block { fill: #453a52; stroke: #b39ddb; }
+html[data-theme="dark"] .offload-block { fill: #5c3a10; stroke: #d9a066; }
+html[data-theme="dark"] .reload-block { fill: #2a4a26; stroke: #81c784; }
+html[data-theme="dark"] .model-block { fill: #333333; stroke: #9e9e9e; }
+html[data-theme="dark"] .wait-block { fill: #4a1d1d; stroke: #ef9a9a; }
+html[data-theme="dark"] .wait-text { fill: #ef9a9a; }
+html[data-theme="dark"] .block-text { fill: #e0e0e0; }
+html[data-theme="dark"] .cpu-box { fill: #2e4a63; stroke: #7ba7cc; }
+html[data-theme="dark"] .gpu-box { fill: #2a4a26; stroke: #81c784; }
+html[data-theme="dark"] .frame-box { fill: #1f1f1f; stroke: #616161; }
+html[data-theme="dark"] .memory-box { fill: #333c47; stroke: #9e9e9e; }
+html[data-theme="dark"] .hbm-box { fill: #1e4620; stroke: #68d391; }
+html[data-theme="dark"] .subtitle,
+html[data-theme="dark"] .memory-label { fill: #e0e0e0; }
+html[data-theme="dark"] .connector { stroke: #bdbdbd; }
+

docs/_static/css/output-style.css

@@ -1,17 +1,31 @@
 /* Custom styling for program output blocks */
 
 .program-output {
-    background-color: #f8f9fa;
-    padding: 0;  /* No padding at all */
-    margin: 0;  /* No margins at all */
-    border-radius: 0;  /* No rounded corners */
+    background-color: #f5f6f8;
+    border: 1px solid #d7dbe0;
+    border-top: none;
+    border-radius: 0 0 4px 4px;
+    padding: 8px 14px;
+    margin: 0 0 1rem 0;
     font-family: 'Courier New', monospace;
     font-size: 14px;
     line-height: 1.5;
     width: 100%;
     max-width: 100%;
 }
 
+/* "Output:" bar attached between a code block and its program output */
+.output-header {
+    background: #eceef1;
+    border: 1px solid #d7dbe0;
+    border-left: 3px solid #9ca3af;
+    padding: 4px 12px;
+    font-size: 12px;
+    color: #4b5563;
+    margin-top: -16px;
+    margin-bottom: 0;
+}
+
 .program-output pre {
     margin: 0;
     padding: 0;
@@ -27,6 +41,14 @@
     width: 100%;
 }
 
+.program-output div[class*="highlight"] {
+    margin: 0;
+}
+
+.program-output pre {
+    padding: 2px 4px;
+}
+
 /* Alternative lighter style */
 .output-block {
     background-color: #fafbfc;
@@ -58,3 +80,62 @@
     background: transparent !important;
 }
 
+/* Header bar attached to the top of a code block ("Needs to be run on...") */
+.code-block-header {
+    background: #f0f4f8;
+    border-left: 3px solid #5c7cfa;
+    padding: 6px 12px;
+    font-size: 13px;
+    color: #495057;
+    margin-bottom: 0;
+    border-radius: 4px 4px 0 0;
+}
+
+.code-block-header + div[class*="highlight"] {
+    margin-top: 0;
+}
+
+/* Dark mode overrides */
+html[data-theme="dark"] .code-block-header {
+    background: #253141;
+    border-left-color: #748ffc;
+    color: #ced4da;
+}
+
+html[data-theme="dark"] .program-output {
+    background-color: #232323;
+    border-color: #444950;
+}
+
+html[data-theme="dark"] .output-header {
+    background: #2f3136;
+    border-color: #444950;
+    border-left-color: #757575;
+    color: #bdbdbd;
+}
+
+html[data-theme="dark"] .program-output pre {
+    color: #e0e0e0;
+}
+
+html[data-theme="dark"] .output-block {
+    background-color: #2b2b2b;
+    border-color: #444950;
+    color: #e0e0e0;
+}
+
+html[data-theme="dark"] .console-output {
+    box-shadow: 0 2px 4px rgba(0, 0, 0, 0.4);
+}
+
+/* pydata forces a light bg on rendered_html outputs in dark mode;
+   ours are pygments code blocks, so darken (same selector, loaded later) */
+html[data-theme="dark"] .bd-content .nboutput .output_area.rendered_html:not(:has(table.dataframe)) {
+    background-color: #1f1f1f;
+    color: #e0e0e0;
+}
+
+html[data-theme="dark"] .output_area.stderr {
+    background: #4a1d1d;
+}
+

docs/_static/css/sphinx_tabs.css

@@ -32,3 +32,25 @@
     background-color: #f9f9f9;
 }
 
+/* Dark mode overrides */
+html[data-theme="dark"] .sphinx-tabs-tab {
+    background-color: #2b2b2b;
+    border-color: #444950;
+    color: #e0e0e0;
+}
+
+html[data-theme="dark"] .sphinx-tabs-tab:hover {
+    background-color: #3a3f44;
+}
+
+html[data-theme="dark"] .sphinx-tabs-tab[aria-selected="true"] {
+    background-color: #76b900;
+    color: #1a1a1a;
+    border-color: #76b900;
+}
+
+html[data-theme="dark"] .sphinx-tabs-panel {
+    background-color: #1f1f1f;
+    border-color: #444950;
+}
+

docs/_static/css/svg-responsive.css

@@ -1,6 +1,13 @@
 /* Responsive styling for project-authored SVG images */
 
-/* Keep embedded SVG content responsive without affecting theme UI icons. */
+/* Keep embedded SVG content responsive without affecting theme UI icons.
+   nvidia_sphinx_theme/pydata-sphinx-theme wraps page content in
+   <article class="bd-article">, not the RTD theme's <div class="document">,
+   and `.. raw:: html :file:` doesn't add a `.raw-html` wrapper -- so these
+   selectors must target the article directly or SVGs with a fixed
+   width/viewBox will overflow the (narrower, "On this page" sidebar-adjacent)
+   content column. */
+article.bd-article svg,
 .document object[type="image/svg+xml"],
 .document .raw-html svg,
 .svg-figure svg {
@@ -13,7 +20,16 @@
     width: 100%;
 }
 
+/* CSS cannot recolor <img>-embedded SVGs: invert lightness instead,
+   hue-rotate(180deg) flips hue back so colors keep their tint */
+html[data-theme="dark"] article.bd-article img[src$=".svg"] {
+    filter: invert(0.88) hue-rotate(180deg);
+    /* undo pydata's white img background (inverts into a gray card) */
+    background: transparent;
+}
+
 /* Ensure container doesn't overflow */
+article.bd-article,
 .document .raw-html {
     max-width: 100%;
     overflow-x: auto;

docs/examples/jax/attention_context_parallel.rst

@@ -125,7 +125,7 @@ while keeping those sharding controls visible.
 
 .. raw:: html
 
-   <div style="background: #f5f5f5; border-left: 3px solid #9ca3af; padding: 4px 12px; font-size: 12px; color: #6b7280; margin-top: -16px;">
+   <div class="output-header">
       Single-GPU output:
    </div>
 
@@ -138,7 +138,7 @@ while keeping those sharding controls visible.
 
 .. raw:: html
 
-   <div style="background: #f5f5f5; border-left: 3px solid #9ca3af; padding: 4px 12px; font-size: 12px; color: #6b7280; margin-top: -16px;">
+   <div class="output-header">
       Ring output:
    </div>
 
@@ -151,7 +151,7 @@ while keeping those sharding controls visible.
 
 .. raw:: html
 
-   <div style="background: #f5f5f5; border-left: 3px solid #9ca3af; padding: 4px 12px; font-size: 12px; color: #6b7280; margin-top: -16px;">
+   <div class="output-header">
       AllGather output:
    </div>
 

docs/examples/jax/attention_single_gpu.rst

@@ -69,7 +69,7 @@ implementations.
 
 .. raw:: html
 
-   <div style="background: #f5f5f5; border-left: 3px solid #9ca3af; padding: 4px 12px; font-size: 12px; color: #6b7280; margin-top: -16px;">
+   <div class="output-header">
       Output:
    </div>
 
@@ -104,7 +104,7 @@ head dimension separately.
 
 .. raw:: html
 
-   <div style="background: #f5f5f5; border-left: 3px solid #9ca3af; padding: 4px 12px; font-size: 12px; color: #6b7280; margin-top: -16px;">
+   <div class="output-header">
       Output:
    </div>