How nipunbatra/ml-teaching works
Project type and purpose
• This is a content-centric repository for an educational Machine Learning course. It is not a runtime application but a _static site_ and _document build_ pipeline.
• Primary functions:
• Host and serve lecture slides (LaTeX → PDF)
• Host and serve interactive notebooks (Jupyter)
• Provide a static website via Quarto/Markdown
• Run quality-control scripts and CI checks
File structure
• Top-level directories:
• slides/navigation: .qmd files (index.qmd, slides.qmd, tutorials.qmd, notebooks.qmd)
• content topics: basics/, maths/, supervised/, neural-networks/, optimization/, unsupervised/, advanced/
• notebooks/: Jupyter .ipynb files
• scripts/: Python utilities for auditing, link-checking, metadata injection
• docs/: design and build documentation
• shared/: common assets (datasets, styles, fonts, notation)
• tests/: automated tests for link and path validation
• build-temp/: transient build artifacts
• Makefile and per-topic Makefiles
• CI workflows: .github/workflows/check-links.yml, publish.yml, validate.yml
README for insights
• Static site generation via Quarto (quarto preview)
• Slide build via Make (make in each folder)
• CI workflows for link validation, content audit, and publishing
• Modular, topic-based approach: each topic folder is self-contained
1. Content Sources
– Markdown/Quarto (.qmd) files (index.qmd, slides.qmd, tutorials.qmd…)
– LaTeX slide sources (.tex) in each topic’s slides/
– Jupyter notebooks (.ipynb)
– Assets (figures, PDFs, datasets) under each topic’s assets/ and shared/
2. Build & Processing Layer
– Makefiles (root Makefile, per-topic Makefile) orchestrating:
• LaTeX compilation → PDFs
• Quarto conversion → HTML site pages
– Python scripts (scripts/*.py) for: link checking, metadata tagging, content auditing
– compile_all_slides.py for batch slide generation
3. Continuous Integration / Deployment (CI/CD)
– GitHub Actions:
• check-links.yml: validate notebook & hyperlink integrity
• validate.yml: run tests/ suite
• publish.yml: deploy built site to GitHub Pages or other hosting
4. Test Suite
– tests/: unit tests to ensure correct paths, slide conventions, asset existence
5. Website / Hosting
– Quarto-generated static site
– Deployed to GitHub Pages (or netlify) using publish CI workflow
6. External Services / Integrations
– Google Colab support for notebooks
– CDN for shared fonts & styles
– GitHub repository hosting
b. Relationships and interactions
• Build outputs PDFs, HTML pages to an “Artifacts” node.
• CI/CD monitors code changes, runs builds & tests, then on success pushes artifacts to Website/Hosting.
• End users consume the Website & PDF slides; instructors clone the repo and run builds locally.
c. Architectural patterns & design principles
• Monorepo with _modular, topic-based_ separation
• _Declarative builds_ via Make + Quarto configuration
• _Separation of concerns_: content vs build vs tests vs deployment
• _Idempotent pipelines_: reproducible outputs from sources
• _CI-driven quality gates_ for links and conventions
d. Key technologies & libraries
• Quarto / Pandoc for static site generation
• LaTeX / Beamer for slide compilation
• Jupyter Notebook for interactive content
• Python scripts for automation and audit
• GitHub Actions for CI/CD
• SCSS/CSS for web styling