mkdocs.yml

site_name: Parallel Programming — GPU + ML Expert Tutor
site_description: >-
  A hands-on curriculum for GPU programming (HIP/CUDA), ML performance
  engineering, and ML system design.
site_author: gahan9
site_url: https://gahan9.github.io/ParallelProgramming/
repo_url: https://github.com/gahan9/ParallelProgramming
repo_name: gahan9/ParallelProgramming
edit_uri: edit/main/

# The curriculum's Markdown lives at the repo ROOT (README, CURRICULUM, tracks/,
# docs/, live/) so GitHub renders it in place with working relative links. MkDocs
# refuses a docs_dir that is the parent of this file, so `build_docs.py` stages the
# publishable files (.md/.html/.css) into _docs/ preserving their relative paths.
# Run it before building:
#     python build_docs.py && mkdocs build --clean
# Both _docs/ and site/ are gitignored.
docs_dir: _docs
site_dir: site

theme:
  name: material
  language: en
  palette:
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: cyan
      accent: indigo
      toggle:
        icon: material/weather-night
        name: Switch to dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: cyan
      accent: indigo
      toggle:
        icon: material/weather-sunny
        name: Switch to light mode
  features:
    # Tracks become a top-level tab strip instead of sitting in the always-visible left
    # rail. This is the single biggest fix for "too nested": the sidebar for any page
    # now shows only the current track's modules, not all 30 modules across 4 tracks.
    - navigation.tabs
    - navigation.tabs.sticky
    - navigation.sections
    - navigation.top
    - navigation.path
    - navigation.prune
    - navigation.indexes
    - navigation.footer
    - search.suggest
    - search.highlight
    - content.code.copy
    - toc.follow

extra_css:
  - docs/stylesheets/brand.css
  - docs/stylesheets/read-aloud.css

extra_javascript:
  # Browser speechSynthesis read-aloud. No dependency and no CDN; the script removes
  # itself on browsers without speech support rather than leaving a dead button.
  - docs/javascripts/read-aloud.js
  # Header buttons that hide/show the left nav rail and the right "On this page" TOC,
  # remembered per-browser via localStorage. Pure UX affordance, no content changes.
  - docs/javascripts/panel-toggle.js
  # Upgrades bare GitHub-style `> [!NOTE]` blockquotes into real Material admonitions
  # client-side, so the 13 modules already using that syntax render as styled, readable
  # callouts (dark-mode included) instead of a raw literal "[!NOTE]" line.
  - docs/javascripts/gfm-alerts.js

markdown_extensions:
  - admonition
  - attr_list
  - md_in_html
  - tables
  # GitHub and Python-Markdown slugify headings differently: Python-Markdown collapses
  # a run of spaces into one hyphen, GitHub emits one hyphen per space. So a heading like
  # "6. Challenges, Drawbacks & Tradeoffs" anchors as `...drawbacks--tradeoffs` on GitHub
  # and `...drawbacks-tradeoffs` here, and any deep link works on exactly one of the two.
  # pymdownx's slugify does not collapse, which makes the two surfaces agree.
  - toc:
      permalink: true
      slugify: !!python/object/apply:pymdownx.slugs.slugify {kwds: {case: lower}}
  - pymdownx.details
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.superfences:
      custom_fences:
        # Renders ```mermaid fences via Material's bundled Mermaid.js.
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format

plugins:
  - search

# Module READMEs link to their own sources (hip/vector_add.cpp, triton/softmax.py) so a
# reader on GitHub can jump straight to the code. Those files are deliberately not
# published to the site, so MkDocs cannot resolve the links and would emit hundreds of
# warnings — which would bury the warnings that actually matter and block `--strict`.
# Silence that one category only; keep nav validation loud.
#
# NOTE: these keys are the MkDocs >= 1.5 schema (nested under `links:`). The flat form
# is silently ignored, which is why the build was noisy before.
validation:
  links:
    not_found: ignore
    absolute_links: ignore
    unrecognized_links: ignore
  nav:
    omitted_files: info
    not_found: warn

# Source files are already excluded by build_docs.py, which stages only .md/.html/.css.
# This is kept as a second line of defence if someone builds against a dirty _docs/.
exclude_docs: |
  requirements*.txt
  profiling_output/
  **/profiling_output/

# Only module READMEs and their exercises/solutions pages are published. Each module's
# drill pages sit under the module entry so the sidebar mirrors the folder layout.
nav:
  - Home: README.md
  - Curriculum: CURRICULUM.md
  - Setup: docs/SETUP.md
  # dashboard.html and slides.html are static files copied verbatim by MkDocs;
  # only the index page can live in nav, and it links to both.
  - Planner & Deck: live/README.md
  - Track A — GPU Programming:
      - Overview: tracks/A-gpu-programming/README.md
      - A01 · Foundations:
          - Module: tracks/A-gpu-programming/A01.foundations-and-programming-model/README.md
          - Exercises: tracks/A-gpu-programming/A01.foundations-and-programming-model/exercises/README.md
          - Solutions: tracks/A-gpu-programming/A01.foundations-and-programming-model/solutions/README.md
      - A02 · Memory Hierarchy & Coalescing:
          - Module: tracks/A-gpu-programming/A02.memory-hierarchy-and-coalescing/README.md
          - Exercises: tracks/A-gpu-programming/A02.memory-hierarchy-and-coalescing/exercises/README.md
          - Solutions: tracks/A-gpu-programming/A02.memory-hierarchy-and-coalescing/solutions/README.md
      - A03 · Execution Model & Occupancy:
          - Module: tracks/A-gpu-programming/A03.execution-model-and-occupancy/README.md
          - Exercises: tracks/A-gpu-programming/A03.execution-model-and-occupancy/exercises/README.md
          - Solutions: tracks/A-gpu-programming/A03.execution-model-and-occupancy/solutions/README.md
      - A04 · Parallel Reduction:
          - Module: tracks/A-gpu-programming/A04.parallel-reduction/README.md
          - Exercises: tracks/A-gpu-programming/A04.parallel-reduction/exercises/README.md
          - Solutions: tracks/A-gpu-programming/A04.parallel-reduction/solutions/README.md
      - A05 · Parallel Scan & Prefix Sum:
          - Module: tracks/A-gpu-programming/A05.parallel-scan-prefix-sum/README.md
          - Exercises: tracks/A-gpu-programming/A05.parallel-scan-prefix-sum/exercises/README.md
          - Solutions: tracks/A-gpu-programming/A05.parallel-scan-prefix-sum/solutions/README.md
      - A06 · Tiled Matrix Multiply:
          - Module: tracks/A-gpu-programming/A06.tiled-matrix-multiply/README.md
          - Exercises: tracks/A-gpu-programming/A06.tiled-matrix-multiply/exercises/README.md
          - Solutions: tracks/A-gpu-programming/A06.tiled-matrix-multiply/solutions/README.md
      - A07 · Softmax & Fused Kernels:
          - Module: tracks/A-gpu-programming/A07.softmax-and-fused-kernels/README.md
          - Exercises: tracks/A-gpu-programming/A07.softmax-and-fused-kernels/exercises/README.md
          - Solutions: tracks/A-gpu-programming/A07.softmax-and-fused-kernels/solutions/README.md
      - A08 · Triton Foundations:
          - Module: tracks/A-gpu-programming/A08.triton-foundations/README.md
          - Exercises: tracks/A-gpu-programming/A08.triton-foundations/exercises/README.md
          - Solutions: tracks/A-gpu-programming/A08.triton-foundations/solutions/README.md
      - A09 · Advanced Triton & FlashAttention:
          - Module: tracks/A-gpu-programming/A09.advanced-triton-flash-attention/README.md
          - Exercises: tracks/A-gpu-programming/A09.advanced-triton-flash-attention/exercises/README.md
          - Solutions: tracks/A-gpu-programming/A09.advanced-triton-flash-attention/solutions/README.md
      - A10 · CuTe, CUTLASS & cuTile (NVIDIA-only):
          - Module: tracks/A-gpu-programming/A10.cute-cutlass-and-cutile/README.md
          - Exercises: tracks/A-gpu-programming/A10.cute-cutlass-and-cutile/exercises/README.md
          - Solutions: tracks/A-gpu-programming/A10.cute-cutlass-and-cutile/solutions/README.md
  - Track B — ML Performance:
      - Overview: tracks/B-gpu-ml-performance/README.md
      - B01 · Accelerator Architecture:
          - Module: tracks/B-gpu-ml-performance/B01.accelerator-architecture/README.md
          - Exercises: tracks/B-gpu-ml-performance/B01.accelerator-architecture/exercises/README.md
          - Solutions: tracks/B-gpu-ml-performance/B01.accelerator-architecture/solutions/README.md
      - B02 · Roofline & Arithmetic Intensity:
          - Module: tracks/B-gpu-ml-performance/B02.roofline-and-arithmetic-intensity/README.md
          - Exercises: tracks/B-gpu-ml-performance/B02.roofline-and-arithmetic-intensity/exercises/README.md
          - Solutions: tracks/B-gpu-ml-performance/B02.roofline-and-arithmetic-intensity/solutions/README.md
      - B03 · Profiling & Bottleneck Analysis:
          - Module: tracks/B-gpu-ml-performance/B03.profiling-and-bottleneck-analysis/README.md
          - Exercises: tracks/B-gpu-ml-performance/B03.profiling-and-bottleneck-analysis/exercises/README.md
          - Solutions: tracks/B-gpu-ml-performance/B03.profiling-and-bottleneck-analysis/solutions/README.md
      - B04 · Precision & Quantization:
          - Module: tracks/B-gpu-ml-performance/B04.precision-and-quantization/README.md
          - Exercises: tracks/B-gpu-ml-performance/B04.precision-and-quantization/exercises/README.md
          - Solutions: tracks/B-gpu-ml-performance/B04.precision-and-quantization/solutions/README.md
      - B05 · Transformer Performance:
          - Module: tracks/B-gpu-ml-performance/B05.transformer-performance/README.md
          - Exercises: tracks/B-gpu-ml-performance/B05.transformer-performance/exercises/README.md
          - Solutions: tracks/B-gpu-ml-performance/B05.transformer-performance/solutions/README.md
      - B06 · Inference Serving Optimizations:
          - Module: tracks/B-gpu-ml-performance/B06.inference-serving-optimizations/README.md
          - Exercises: tracks/B-gpu-ml-performance/B06.inference-serving-optimizations/exercises/README.md
          - Solutions: tracks/B-gpu-ml-performance/B06.inference-serving-optimizations/solutions/README.md
      - B07 · Distributed Training & Sharding:
          - Module: tracks/B-gpu-ml-performance/B07.distributed-training-and-sharding/README.md
          - Exercises: tracks/B-gpu-ml-performance/B07.distributed-training-and-sharding/exercises/README.md
          - Solutions: tracks/B-gpu-ml-performance/B07.distributed-training-and-sharding/solutions/README.md
  - Track C — ML System Design:
      - Overview: tracks/C-ml-system-design/README.md
      - C01 · Problem Framing & Metrics:
          - Module: tracks/C-ml-system-design/C01.problem-framing-and-metrics/README.md
          - Exercises: tracks/C-ml-system-design/C01.problem-framing-and-metrics/exercises/README.md
          - Solutions: tracks/C-ml-system-design/C01.problem-framing-and-metrics/solutions/README.md
      - C02 · Data Pipelines & Features:
          - Module: tracks/C-ml-system-design/C02.data-pipelines-and-features/README.md
          - Exercises: tracks/C-ml-system-design/C02.data-pipelines-and-features/exercises/README.md
          - Solutions: tracks/C-ml-system-design/C02.data-pipelines-and-features/solutions/README.md
      - C03 · Training Systems:
          - Module: tracks/C-ml-system-design/C03.training-systems/README.md
          - Exercises: tracks/C-ml-system-design/C03.training-systems/exercises/README.md
          - Solutions: tracks/C-ml-system-design/C03.training-systems/solutions/README.md
      - C04 · Production Model Optimization:
          - Module: tracks/C-ml-system-design/C04.production-model-optimization/README.md
          - Exercises: tracks/C-ml-system-design/C04.production-model-optimization/exercises/README.md
          - Solutions: tracks/C-ml-system-design/C04.production-model-optimization/solutions/README.md
      - C05 · Deployment & Serving Architecture:
          - Module: tracks/C-ml-system-design/C05.deployment-and-serving-architecture/README.md
          - Exercises: tracks/C-ml-system-design/C05.deployment-and-serving-architecture/exercises/README.md
          - Solutions: tracks/C-ml-system-design/C05.deployment-and-serving-architecture/solutions/README.md
      - C06 · Monitoring, Drift & Ethics:
          - Module: tracks/C-ml-system-design/C06.monitoring-drift-and-ethics/README.md
          - Exercises: tracks/C-ml-system-design/C06.monitoring-drift-and-ethics/exercises/README.md
          - Solutions: tracks/C-ml-system-design/C06.monitoring-drift-and-ethics/solutions/README.md
      - C07 · Capstone Case Studies:
          - Module: tracks/C-ml-system-design/C07.capstone-case-studies/README.md
          - LLM Serving Design: tracks/C-ml-system-design/C07.capstone-case-studies/designs/llm_serving.md
          - Recommender Design: tracks/C-ml-system-design/C07.capstone-case-studies/designs/recommender.md
          - Exercises: tracks/C-ml-system-design/C07.capstone-case-studies/exercises/README.md
          - Solutions: tracks/C-ml-system-design/C07.capstone-case-studies/solutions/README.md
  - Track D — Distributed Computing:
      - Overview: tracks/D-distributed-computing/README.md
      - D01 · Scaling Limits & Communication Cost:
          - Module: tracks/D-distributed-computing/D01.scaling-limits-and-communication-cost/README.md
          - Exercises: tracks/D-distributed-computing/D01.scaling-limits-and-communication-cost/exercises/README.md
          - Solutions: tracks/D-distributed-computing/D01.scaling-limits-and-communication-cost/solutions/README.md
      - D02 · Message Passing with MPI:
          - Module: tracks/D-distributed-computing/D02.message-passing-and-mpi/README.md
          - Exercises: tracks/D-distributed-computing/D02.message-passing-and-mpi/exercises/README.md
          - Solutions: tracks/D-distributed-computing/D02.message-passing-and-mpi/solutions/README.md
      - D03 · GPU Collectives (NCCL & RCCL):
          - Module: tracks/D-distributed-computing/D03.gpu-collectives-nccl-and-rccl/README.md
          - Exercises: tracks/D-distributed-computing/D03.gpu-collectives-nccl-and-rccl/exercises/README.md
          - Solutions: tracks/D-distributed-computing/D03.gpu-collectives-nccl-and-rccl/solutions/README.md
      - D04 · Interconnects & RDMA:
          - Module: tracks/D-distributed-computing/D04.interconnects-and-rdma/README.md
          - Exercises: tracks/D-distributed-computing/D04.interconnects-and-rdma/exercises/README.md
          - Solutions: tracks/D-distributed-computing/D04.interconnects-and-rdma/solutions/README.md
      - D05 · Topology & Scale Boundaries:
          - Module: tracks/D-distributed-computing/D05.topology-and-scale-boundaries/README.md
          - Exercises: tracks/D-distributed-computing/D05.topology-and-scale-boundaries/exercises/README.md
          - Solutions: tracks/D-distributed-computing/D05.topology-and-scale-boundaries/solutions/README.md
      - D06 · Real Systems at Scale:
          - Module: tracks/D-distributed-computing/D06.real-systems-at-scale/README.md
          - Exercises: tracks/D-distributed-computing/D06.real-systems-at-scale/exercises/README.md
          - Solutions: tracks/D-distributed-computing/D06.real-systems-at-scale/solutions/README.md
  - Content Studio:
      - Overview: content/README.md
      - Storyboard Template: content/STORYBOARD_TEMPLATE.md
      - Brand Overlay Spec: content/BRAND_OVERLAY.md
  - Reference:
      - Brand & Visual Identity: docs/BRAND.md
      - Glossary: docs/GLOSSARY.md
      - References: docs/REFERENCES.md
      - Module Template: docs/MODULE_TEMPLATE.md