Skip to content

Commit f471967

Browse files
rich-iannonerich-iannone
authored
Merge pull request #313 from posit-dev/docs-pdf-version-user-guide
docs: Add PDF version of user guide
2 parents e957f58 + c3f2e6a commit f471967

File tree

10 files changed

+1000
-0
lines changed

10 files changed

+1000
-0
lines changed

‎.gitignore‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -119,6 +119,12 @@ docs/_site
119119
docs/.quarto
120120
docs/reference
121121
docs/objects.json
122+
docs/user-guide-pdf-clean.qmd
123+
docs/toc.html
124+
docs/toc.pdf
125+
docs/user-guilde-with-toc.pdf
126+
docs/basic_validation.yaml
127+
docs/validation_config.yaml
122128

123129
datasets/
124130
/*.parquet

‎Makefile‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,17 @@ docs-build:
6363
&& quartodoc build --verbose \
6464
&& quarto render
6565

66+
docs-pdf: ## Build PDF version of User Guide (HTML to PDF preserving graphics)
67+
@echo "Preparing PDF document (stripping YAML from includes)..."
68+
uv run python scripts/create_pdf_doc.py
69+
@echo "Rendering User Guide to self-contained HTML..."
70+
cd docs && uv run quarto render user-guide-pdf-clean.qmd --to html --output user-guide-pdf.html
71+
@echo "Converting HTML to PDF with Chrome (preserves validation reports)..."
72+
uv run python scripts/html_to_pdf.py docs/_site/user-guide-pdf.html docs/user-guide.pdf
73+
@echo "Creating Table of Contents page with actual page numbers..."
74+
uv run python scripts/create_toc_pdf.py docs/user-guide.pdf
75+
@echo "PDF available at docs/user-guide.pdf"
76+
6677
docs-llms: ## Generate llms.txt and llms-full.txt files for LLM consumption
6778
@uv run python scripts/generate_llms_txt.py
6879

‎docs/_quarto.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ project:
33
post-render: scripts/post-render.py
44
resources:
55
- "assets/**"
6+
- "user-guide.pdf"
67

78
format:
89
html:
@@ -55,6 +56,9 @@ website:
5556
text: API Reference
5657
- href: blog/index.qmd
5758
text: Pointblog
59+
- text: "User Guide (PDF)"
60+
icon: file-pdf
61+
href: user-guide.pdf
5862
right:
5963
- icon: discord
6064
href: https://discord.com/invite/YH7CybCNCQ

‎docs/assets/pointblank_logo.png‎

132 KB
Loading

‎docs/print-styles.css‎

Lines changed: 217 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,217 @@
1+
/* Print-specific styles for PDF generation */
2+
3+
@media print {
4+
/* Page settings - page numbers added via post-processing */
5+
@page {
6+
size: letter landscape;
7+
margin: 0.5in;
8+
}
9+
10+
/* Hide navigation and other UI elements for PDF (but keep TOC) */
11+
nav.navbar:not(#TOC),
12+
.nav-footer,
13+
#quarto-header,
14+
.quarto-title-banner,
15+
.quarto-title,
16+
header.quarto-title-block,
17+
.sidebar,
18+
#quarto-sidebar,
19+
.page-navigation {
20+
display: none !important;
21+
}
22+
23+
/* Show and style the TOC for PDF */
24+
#TOC,
25+
nav#TOC {
26+
display: block !important;
27+
page-break-after: always;
28+
page-break-before: auto;
29+
margin: 1in auto;
30+
max-width: 8in;
31+
padding: 1em;
32+
}
33+
34+
#TOC::before,
35+
nav#TOC::before {
36+
content: "Table of Contents";
37+
display: block;
38+
font-size: 24pt;
39+
font-weight: bold;
40+
margin-bottom: 0.75em;
41+
}
42+
43+
#TOC ul,
44+
nav#TOC ul {
45+
list-style: none;
46+
padding-left: 0;
47+
}
48+
49+
#TOC li,
50+
nav#TOC li {
51+
margin: 0.5em 0;
52+
line-height: 1.4;
53+
}
54+
55+
#TOC ul ul,
56+
nav#TOC ul ul {
57+
padding-left: 1.5em;
58+
font-size: 0.9em;
59+
}
60+
61+
#TOC a,
62+
nav#TOC a {
63+
text-decoration: none;
64+
color: #333;
65+
}
66+
67+
#TOC a::after,
68+
nav#TOC a::after {
69+
content: leader('.') target-counter(attr(href), page);
70+
}
71+
72+
/* Manual Table of Contents */
73+
.manual-toc {
74+
page-break-after: always;
75+
page-break-inside: avoid;
76+
padding: 2em;
77+
max-width: 8in;
78+
margin: 0 auto;
79+
}
80+
81+
.manual-toc h1 {
82+
font-size: 24pt;
83+
margin-bottom: 1.5em;
84+
text-align: center;
85+
}
86+
87+
.manual-toc ol {
88+
list-style: none;
89+
padding: 0;
90+
font-size: 14pt;
91+
line-height: 2.5;
92+
}
93+
94+
.manual-toc li {
95+
margin: 0.75em 0;
96+
position: relative;
97+
}
98+
99+
.manual-toc a {
100+
text-decoration: none;
101+
color: #333;
102+
}
103+
104+
/* Style the title page */
105+
.title-page {
106+
page-break-after: always;
107+
page-break-inside: avoid;
108+
text-align: center;
109+
margin: 0;
110+
padding: 0;
111+
min-height: 8in;
112+
}
113+
114+
/* Page break utility */
115+
.page-break {
116+
page-break-after: always;
117+
height: 0;
118+
margin: 0;
119+
padding: 0;
120+
}
121+
122+
.title-page * {
123+
page-break-before: avoid !important;
124+
page-break-after: avoid !important;
125+
}
126+
127+
/* Page break helper */
128+
.page-break {
129+
page-break-after: always;
130+
height: 0;
131+
margin: 0;
132+
padding: 0;
133+
}
134+
135+
/* Avoid page breaks inside important elements */
136+
.validation-report,
137+
pre,
138+
code,
139+
img {
140+
page-break-inside: avoid;
141+
}
142+
143+
/* Ensure links are visible */
144+
a[href]:after {
145+
content: none !important;
146+
}
147+
148+
/* Optimize table rendering - reduce font size for wide tables */
149+
table {
150+
width: 100%;
151+
border-collapse: collapse;
152+
font-size: 9pt;
153+
page-break-inside: avoid;
154+
page-break-before: auto;
155+
page-break-after: auto;
156+
}
157+
158+
table th, table td {
159+
padding: 4px 6px;
160+
font-size: 8pt;
161+
page-break-inside: avoid;
162+
}
163+
164+
/* Make validation tables more compact */
165+
.validation-report table {
166+
font-size: 7pt;
167+
}
168+
169+
.validation-report table th,
170+
.validation-report table td {
171+
padding: 2px 4px;
172+
}
173+
174+
/* Ensure table containers don't break */
175+
.cell-output,
176+
.cell-output-display,
177+
div:has(> table) {
178+
page-break-inside: avoid;
179+
}
180+
181+
/* Ensure code blocks fit */
182+
pre code {
183+
font-size: 8pt;
184+
white-space: pre-wrap;
185+
word-wrap: break-word;
186+
}
187+
188+
/* Better header spacing and page breaks */
189+
h1 {
190+
page-break-before: always;
191+
page-break-after: avoid;
192+
page-break-inside: avoid;
193+
margin-top: 0;
194+
}
195+
196+
/* Don't break page before the first h1 */
197+
body > h1:first-of-type,
198+
main > h1:first-of-type,
199+
#quarto-content > h1:first-of-type {
200+
page-break-before: avoid;
201+
}
202+
203+
h2, h3, h4, h5, h6 {
204+
page-break-after: avoid;
205+
page-break-inside: avoid;
206+
}
207+
208+
/* Ensure images fit on page */
209+
img {
210+
max-width: 100%;
211+
height: auto;
212+
}
213+
}
214+
215+
@media screen {
216+
/* Screen-only: add print preview button styles if needed */
217+
}

‎docs/user-guide-pdf.qmd‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
---
2+
format:
3+
html:
4+
toc: true
5+
toc-depth: 3
6+
number-sections: true
7+
embed-resources: true
8+
theme: flatly
9+
css:
10+
- styles.css
11+
- print-styles.css
12+
page-layout: full
13+
self-contained: true
14+
jupyter: python3
15+
---
16+
17+
```{python}
18+
#| echo: false
19+
#| output: false
20+
import pointblank as pb
21+
pb.config(report_incl_footer=False)
22+
```
23+
24+
::: {.title-page}
25+
26+
![](assets/pointblank_logo.png){width=400px style="display: block; margin: 0 auto; margin-top: 2in; margin-bottom: 0.75in;"}
27+
28+
<p style="text-align: center; font-size: 18pt; line-height: 1.6; max-width: 700px; margin: 0 auto;">
29+
Data validation toolkit for assessing and monitoring data quality.
30+
</p>
31+
32+
<p style="text-align: center; font-size: 10pt; color: #666; position: absolute; bottom: 1in; left: 0; right: 0;">
33+
&copy; 2024&ndash;2025 Posit Software, PBC
34+
</p>
35+
36+
:::
37+
38+
# Validation Plan
39+
40+
{{< include user-guide/validation-overview.qmd >}}
41+
42+
{{< include user-guide/validation-methods.qmd >}}
43+
44+
{{< include user-guide/column-selection-patterns.qmd >}}
45+
46+
{{< include user-guide/preprocessing.qmd >}}
47+
48+
{{< include user-guide/segmentation.qmd >}}
49+
50+
{{< include user-guide/thresholds.qmd >}}
51+
52+
{{< include user-guide/actions.qmd >}}
53+
54+
{{< include user-guide/briefs.qmd >}}
55+
56+
# Advanced Validation
57+
58+
{{< include user-guide/expressions.qmd >}}
59+
60+
{{< include user-guide/schema-validation.qmd >}}
61+
62+
{{< include user-guide/assertions.qmd >}}
63+
64+
{{< include user-guide/draft-validation.qmd >}}
65+
66+
# YAML
67+
68+
{{< include user-guide/yaml-validation-workflows.qmd >}}
69+
70+
{{< include user-guide/yaml-reference.qmd >}}
71+
72+
# Post Interrogation
73+
74+
{{< include user-guide/validation-reports.qmd >}}
75+
76+
{{< include user-guide/step-reports.qmd >}}
77+
78+
{{< include user-guide/extracts.qmd >}}
79+
80+
{{< include user-guide/sundering.qmd >}}
81+
82+
# Data Inspection
83+
84+
{{< include user-guide/preview.qmd >}}
85+
86+
{{< include user-guide/col-summary-tbl.qmd >}}
87+
88+
{{< include user-guide/missing-vals-tbl.qmd >}}
89+
90+
# The Pointblank CLI
91+
92+
{{< include user-guide/cli-data-inspection.qmd >}}
93+
94+
{{< include user-guide/cli-data-validation.qmd >}}
95+
96+
{{< include user-guide/cli-reference.qmd >}}
97+

‎docs/user-guide.pdf‎

6.49 MB
Binary file not shown.

0 commit comments

Comments
 (0)