Skip to content

All.notes to pdf.explanation

Flow Explanation#

  • This document walks through the architecture of the notes_to_pdf.py script.

Goal#

  • Convert a lightweight, annotated plain-text notes file (usually *.txt) into a share-ready document.
    • Formats include PDF, HTML, or Beamer slide deck
  • Ensure the following:
    • Honor rich Markdown features and custom shorthand.
    • Inline auto-generated diagrams:
      • PlantUML
      • Mermaid
      • TikZ
      • Graphviz
      • LaTeX tables

Architecture diagram#

%%{init: {'theme':'default'}}%%
C4Context

System_Ext(user, "User", "Author preparing course notes")
System(doc, "Documentation Toolchain", "Python & LaTeX")

System_Boundary(doc_boundary, "") {
    Container(notes2pdf, "notes_to_pdf.py", "Python CLI", "Orchestrates conversion: clean -> images -> Pandoc -> LaTeX")
    Container(render, "render_images.py", "Python module", "Renders diagram blocks to images. Caches results.")
    Container(preproc, "preprocess_notes.py", "Python module", "Cleans notes & expands macros (pre-Pandoc)")
    Container(style, "latex_abbrevs.sty", "LaTeX style", "Provides LaTeX math & formatting shortcuts")
}

Rel(user, notes2pdf, "Invokes via CLI")
Rel(notes2pdf, preproc, "Uses for Note Pre-processing")
Rel(notes2pdf, render, "Calls to Render Images")
Rel(notes2pdf, style, "Injects LaTeX Style (.sty)")

Steps#

  1. Clean-up & augmentation

  2. Performed by: preprocess_notes.py

  3. Key ideas:

    • Normalizes headers
    • Expands arrow shorthand (-> to \rightarrow)
    • Deals with comments
    • Inserts Pandoc YAML front-matter
    • Inserts optional navigation slides

  4. Diagram extraction

  5. Performed by: render_images.py

  6. Key ideas:

    • Scans code blocks (e.g., ` plantuml)
    • Renders diagrams via Docker containers
    • Replaces the code with ![](figs/...) include
    • Comments out the original block
    • Uses a SHA-256 cache to skip unchanged diagrams

  7. Orchestration

  8. Performed by: notes_to_pdf.py

  9. Key ideas:

    • Calls Stage 1 and Stage 2, then Pandoc, then (for PDF) LaTeX
    • Flags control each sub-action to allow skipping, debugging, or re-running steps individually

  10. Document synthesis

  11. Performed by: Pandoc + LaTeX

  12. Key ideas:
    • Pandoc converts Markdown to LaTeX (or HTML / Beamer)
    • latex_abbrevs.sty is copied next to the generated .tex file
    • Ensures vector/matrix macros (\vv{}, \mat{}), deep lists, and color helpers compile correctly

Dependencies#

preprocess_notes.py#

  • Input: Raw notes.
  • Output: Pandoc‑ready Markdown.
  • Handles
    • Formatting banner frames.
    • Question formatting.
    • Colour commands (\red{} -> \textcolor{red}{...}).
    • TOC injection.

render_images.py#

  • Docker‑wrapper around PlantUML, Mermaid CLI, TikZ, Graphviz to convert image description in a file, replacing the text with the picture. figs/<basename>.<index>.png

latex_abbrevs.sty#

  • Custom style for Latex documents, including:
    • Bold-underlined vectors (\vv{x})
    • Matrices
    • Colour presets
    • 9-level enumitem lists
    • Symbol shorthands
  • Copied automatically; you rarely touch this unless you need new macros.