docs: Add PDF version of user guide

.gitignore

@@ -119,6 +119,12 @@ docs/_site
 docs/.quarto
 docs/reference
 docs/objects.json
+docs/user-guide-pdf-clean.qmd
+docs/toc.html
+docs/toc.pdf
+docs/user-guilde-with-toc.pdf
+docs/basic_validation.yaml
+docs/validation_config.yaml
 
 datasets/
 /*.parquet

Makefile

@@ -63,6 +63,17 @@ docs-build:
 	  && quartodoc build --verbose \
 	  && quarto render
 
+docs-pdf: ## Build PDF version of User Guide (HTML to PDF preserving graphics)
+	@echo "Preparing PDF document (stripping YAML from includes)..."
+	uv run python scripts/create_pdf_doc.py
+	@echo "Rendering User Guide to self-contained HTML..."
+	cd docs && uv run quarto render user-guide-pdf-clean.qmd --to html --output user-guide-pdf.html
+	@echo "Converting HTML to PDF with Chrome (preserves validation reports)..."
+	uv run python scripts/html_to_pdf.py docs/_site/user-guide-pdf.html docs/user-guide.pdf
+	@echo "Creating Table of Contents page with actual page numbers..."
+	uv run python scripts/create_toc_pdf.py docs/user-guide.pdf
+	@echo "PDF available at docs/user-guide.pdf"
+
 docs-llms: ## Generate llms.txt and llms-full.txt files for LLM consumption
 	@uv run python scripts/generate_llms_txt.py
 

docs/_quarto.yml

@@ -3,6 +3,7 @@ project:
   post-render: scripts/post-render.py
   resources:
     - "assets/**"
+    - "user-guide.pdf"
 
 format:
   html:
@@ -55,6 +56,9 @@ website:
         text: API Reference
       - href: blog/index.qmd
         text: Pointblog
+      - text: "User Guide (PDF)"
+        icon: file-pdf
+        href: user-guide.pdf
     right:
       - icon: discord
         href: https://discord.com/invite/YH7CybCNCQ

docs/print-styles.css

@@ -0,0 +1,217 @@
+/* Print-specific styles for PDF generation */
+
+@media print {
+  /* Page settings - page numbers added via post-processing */
+  @page {
+    size: letter landscape;
+    margin: 0.5in;
+  }
+
+  /* Hide navigation and other UI elements for PDF (but keep TOC) */
+  nav.navbar:not(#TOC),
+  .nav-footer,
+  #quarto-header,
+  .quarto-title-banner,
+  .quarto-title,
+  header.quarto-title-block,
+  .sidebar,
+  #quarto-sidebar,
+  .page-navigation {
+    display: none !important;
+  }
+
+  /* Show and style the TOC for PDF */
+  #TOC,
+  nav#TOC {
+    display: block !important;
+    page-break-after: always;
+    page-break-before: auto;
+    margin: 1in auto;
+    max-width: 8in;
+    padding: 1em;
+  }
+
+  #TOC::before,
+  nav#TOC::before {
+    content: "Table of Contents";
+    display: block;
+    font-size: 24pt;
+    font-weight: bold;
+    margin-bottom: 0.75em;
+  }
+
+  #TOC ul,
+  nav#TOC ul {
+    list-style: none;
+    padding-left: 0;
+  }
+
+  #TOC li,
+  nav#TOC li {
+    margin: 0.5em 0;
+    line-height: 1.4;
+  }
+
+  #TOC ul ul,
+  nav#TOC ul ul {
+    padding-left: 1.5em;
+    font-size: 0.9em;
+  }
+
+  #TOC a,
+  nav#TOC a {
+    text-decoration: none;
+    color: #333;
+  }
+
+  #TOC a::after,
+  nav#TOC a::after {
+    content: leader('.') target-counter(attr(href), page);
+  }
+
+  /* Manual Table of Contents */
+  .manual-toc {
+    page-break-after: always;
+    page-break-inside: avoid;
+    padding: 2em;
+    max-width: 8in;
+    margin: 0 auto;
+  }
+
+  .manual-toc h1 {
+    font-size: 24pt;
+    margin-bottom: 1.5em;
+    text-align: center;
+  }
+
+  .manual-toc ol {
+    list-style: none;
+    padding: 0;
+    font-size: 14pt;
+    line-height: 2.5;
+  }
+
+  .manual-toc li {
+    margin: 0.75em 0;
+    position: relative;
+  }
+
+  .manual-toc a {
+    text-decoration: none;
+    color: #333;
+  }
+
+  /* Style the title page */
+  .title-page {
+    page-break-after: always;
+    page-break-inside: avoid;
+    text-align: center;
+    margin: 0;
+    padding: 0;
+    min-height: 8in;
+  }
+
+  /* Page break utility */
+  .page-break {
+    page-break-after: always;
+    height: 0;
+    margin: 0;
+    padding: 0;
+  }
+
+  .title-page * {
+    page-break-before: avoid !important;
+    page-break-after: avoid !important;
+  }
+
+  /* Page break helper */
+  .page-break {
+    page-break-after: always;
+    height: 0;
+    margin: 0;
+    padding: 0;
+  }
+
+  /* Avoid page breaks inside important elements */
+  .validation-report,
+  pre,
+  code,
+  img {
+    page-break-inside: avoid;
+  }
+
+  /* Ensure links are visible */
+  a[href]:after {
+    content: none !important;
+  }
+
+  /* Optimize table rendering - reduce font size for wide tables */
+  table {
+    width: 100%;
+    border-collapse: collapse;
+    font-size: 9pt;
+    page-break-inside: avoid;
+    page-break-before: auto;
+    page-break-after: auto;
+  }
+
+  table th, table td {
+    padding: 4px 6px;
+    font-size: 8pt;
+    page-break-inside: avoid;
+  }
+
+  /* Make validation tables more compact */
+  .validation-report table {
+    font-size: 7pt;
+  }
+
+  .validation-report table th,
+  .validation-report table td {
+    padding: 2px 4px;
+  }
+
+  /* Ensure table containers don't break */
+  .cell-output,
+  .cell-output-display,
+  div:has(> table) {
+    page-break-inside: avoid;
+  }
+
+  /* Ensure code blocks fit */
+  pre code {
+    font-size: 8pt;
+    white-space: pre-wrap;
+    word-wrap: break-word;
+  }
+
+  /* Better header spacing and page breaks */
+  h1 {
+    page-break-before: always;
+    page-break-after: avoid;
+    page-break-inside: avoid;
+    margin-top: 0;
+  }
+
+  /* Don't break page before the first h1 */
+  body > h1:first-of-type,
+  main > h1:first-of-type,
+  #quarto-content > h1:first-of-type {
+    page-break-before: avoid;
+  }
+
+  h2, h3, h4, h5, h6 {
+    page-break-after: avoid;
+    page-break-inside: avoid;
+  }
+
+  /* Ensure images fit on page */
+  img {
+    max-width: 100%;
+    height: auto;
+  }
+}
+
+@media screen {
+  /* Screen-only: add print preview button styles if needed */
+}

docs/user-guide-pdf.qmd

@@ -0,0 +1,97 @@
+---
+format:
+  html:
+    toc: true
+    toc-depth: 3
+    number-sections: true
+    embed-resources: true
+    theme: flatly
+    css:
+      - styles.css
+      - print-styles.css
+    page-layout: full
+    self-contained: true
+jupyter: python3
+---
+
+```{python}
+#| echo: false
+#| output: false
+import pointblank as pb
+pb.config(report_incl_footer=False)
+```
+
+::: {.title-page}
+
+![](assets/pointblank_logo.png){width=400px style="display: block; margin: 0 auto; margin-top: 2in; margin-bottom: 0.75in;"}
+
+<p style="text-align: center; font-size: 18pt; line-height: 1.6; max-width: 700px; margin: 0 auto;">
+Data validation toolkit for assessing and monitoring data quality.
+</p>
+
+<p style="text-align: center; font-size: 10pt; color: #666; position: absolute; bottom: 1in; left: 0; right: 0;">
+&copy; 2024&ndash;2025 Posit Software, PBC
+</p>
+
+:::
+
+# Validation Plan
+
+{{< include user-guide/validation-overview.qmd >}}
+
+{{< include user-guide/validation-methods.qmd >}}
+
+{{< include user-guide/column-selection-patterns.qmd >}}
+
+{{< include user-guide/preprocessing.qmd >}}
+
+{{< include user-guide/segmentation.qmd >}}
+
+{{< include user-guide/thresholds.qmd >}}
+
+{{< include user-guide/actions.qmd >}}
+
+{{< include user-guide/briefs.qmd >}}
+
+# Advanced Validation
+
+{{< include user-guide/expressions.qmd >}}
+
+{{< include user-guide/schema-validation.qmd >}}
+
+{{< include user-guide/assertions.qmd >}}
+
+{{< include user-guide/draft-validation.qmd >}}
+
+# YAML
+
+{{< include user-guide/yaml-validation-workflows.qmd >}}
+
+{{< include user-guide/yaml-reference.qmd >}}
+
+# Post Interrogation
+
+{{< include user-guide/validation-reports.qmd >}}
+
+{{< include user-guide/step-reports.qmd >}}
+
+{{< include user-guide/extracts.qmd >}}
+
+{{< include user-guide/sundering.qmd >}}
+
+# Data Inspection
+
+{{< include user-guide/preview.qmd >}}
+
+{{< include user-guide/col-summary-tbl.qmd >}}
+
+{{< include user-guide/missing-vals-tbl.qmd >}}
+
+# The Pointblank CLI
+
+{{< include user-guide/cli-data-inspection.qmd >}}
+
+{{< include user-guide/cli-data-validation.qmd >}}
+
+{{< include user-guide/cli-reference.qmd >}}
+