Skip to content

Commit 2c390da

Browse files
dannyadairdannyadair
committed
docs: Add "Usage" document, adjust README and overview, fix custom locations
1 parent cd4c675 commit 2c390da

File tree

4 files changed

+262
-33
lines changed

4 files changed

+262
-33
lines changed

‎README.md‎

Lines changed: 61 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -14,9 +14,7 @@
1414

1515
Create PDF documents from YAML-configured SVG templates.
1616

17-
## Quickstart
18-
19-
### Installation
17+
## Installation
2018

2119
pdfbaker is available on [PyPI](https://pypi.org/project/pdfbaker/) and can be installed
2220
using [pipx](https://github.com/pypa/pipx):
@@ -33,17 +31,17 @@ sudo apt install pipx
3331
pipx ensurepath
3432
```
3533

36-
#### Windows Requirements
34+
### Windows Requirements
3735

3836
If you are using Windows, GTK needs to be installed:
3937
[GTK for Windows Runtime Environment Installer](https://github.com/tschoonj/GTK-for-Windows-Runtime-Environment-Installer/releases/download/2022-01-04/gtk3-runtime-3.24.31-2022-01-04-ts-win64.exe)
4038

4139
- Choose Install GTK+ libraries
42-
- Tick to setup path (otherwise add the install dll folder manually)
40+
- Tick to setup path (otherwise add the install DLL folder manually)
4341
- Choose your installation location
4442
- Complete the installation
4543

46-
### Optional Dependencies
44+
## Optional Dependencies
4745

4846
- For SVG to PDF conversion, [CairoSVG](https://cairosvg.org/) is used by default. If
4947
you need [Inkscape](https://inkscape.org/) instead, install it:
@@ -64,30 +62,60 @@ If you are using Windows, GTK needs to be installed:
6462
sudo apt install fonts-roboto
6563
```
6664

67-
### Basic Usage
65+
## Quickstart: Create templated PDF from an SVG
6866

69-
1. Create your document design in an SVG editor
70-
2. Replace text with variables using Jinja2 (e.g., `{{ title }}`)
71-
3. Configure your content in YAML
72-
4. Generate PDFs with:
67+
The fastest way to get started is with the `--create-from` option:
7368

74-
```bash
75-
pdfbaker <config_file>
76-
```
69+
1. Design your document in an SVG editor or convert to SVG.
70+
2. Run pdfbaker with `--create-from` to scaffold a new project and generate your first
71+
PDF:
72+
73+
```bash
74+
pdfbaker --create-from mydesign.svg myproject/myproject.yaml
75+
```
76+
77+
This will create a directory structure like:
78+
79+
```bash
80+
myproject
81+
├── myproject.yaml
82+
└── mydesign
83+
├── config.yaml
84+
├── pages
85+
│   └── main.yaml
86+
└── templates
87+
└── main.svg.j2
88+
```
7789

78-
This will produce your PDF files in a `dist/` directory where your configuration file
79-
lives. It will also create a `build/` directory with intermediate files, which is only
80-
kept if you specify `--keep-build-files` (or `--debug`).
90+
and produce your PDF in `myproject/dist/mydesign/mydesign.pdf`.
91+
92+
3. Edit the template and YAML files to customize your content and variables. This
93+
directory structure is just a starting point. Add more documents and customize as
94+
needed.
95+
96+
4. For future builds, just run:
97+
98+
```bash
99+
pdfbaker myproject/myproject.yaml
100+
```
101+
102+
to regenerate your PDFs.
81103

82104
## Examples
83105

84-
For working examples, see the [examples](examples) directory:
106+
For working examples, see the
107+
[examples](https://github.com/pythonnz/pdfbaker/tree/main/examples) directory:
85108

86-
- [minimal](examples/minimal) - Basic usage
87-
- [regular](examples/regular) - Standard features
88-
- [variants](examples/variants) - Document variants
89-
- [custom_locations](examples/custom_locations) - Custom file/directory locations
90-
- [custom_processing](examples/custom_processing) - Custom processing with Python
109+
- [minimal](https://github.com/pythonnz/pdfbaker/tree/main/examples/minimal) - Basic
110+
usage
111+
- [regular](https://github.com/pythonnz/pdfbaker/tree/main/examples/regular) - Standard
112+
features
113+
- [variants](https://github.com/pythonnz/pdfbaker/tree/main/examples/variants) -
114+
Document variants
115+
- [custom_locations](https://github.com/pythonnz/pdfbaker/tree/main/examples/custom_locations) -
116+
Custom file/directory locations
117+
- [custom_processing](https://github.com/pythonnz/pdfbaker/tree/main/examples/custom_processing) -
118+
Custom processing with Python
91119

92120
Create all PDFs with:
93121

@@ -97,12 +125,16 @@ pdfbaker examples/examples.yaml
97125

98126
## Documentation
99127

100-
- [Overview](docs/overview.md) - Start here
101-
- [Configuration Reference](docs/configuration.md) - All available settings
102-
- [Document Variants](docs/variants.md) - Create multiple versions of the same document
103-
- [Custom Processing](docs/custom_processing.md) - Provide page content from anywhere
104-
105-
( [on GitHub](https://github.com/pythonnz/pdfbaker/tree/main/docs) )
128+
- [Overview](https://github.com/pythonnz/pdfbaker/blob/main/docs/overview.md) - Start
129+
here
130+
- [Usage](https://github.com/pythonnz/pdfbaker/blob/main/docs/usage.md) - From the CLI
131+
or as a library
132+
- [Configuration Reference](https://github.com/pythonnz/pdfbaker/blob/main/docs/configuration.md) -
133+
All available settings
134+
- [Document Variants](https://github.com/pythonnz/pdfbaker/blob/main/docs/variants.md) -
135+
Create multiple versions of the same document
136+
- [Custom Processing](https://github.com/pythonnz/pdfbaker/blob/main/docs/custom_processing.md) -
137+
Provide page content from anywhere
106138

107139
## Development
108140

‎docs/configuration.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -294,8 +294,8 @@ You can customize all directories / file locations, even on a per-document basis
294294
# Document configuration
295295
filename: Monthly Report
296296
directories:
297-
- images: "../../images"
298-
- dist: "/var/www/documents"
297+
images: "../../images"
298+
dist: "/var/www/documents"
299299
pages:
300300
- main
301301
```

‎docs/overview.md‎

Lines changed: 71 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,15 +21,15 @@ overlapping elements, specific fonts or custom shapes:
2121
Configuring and editing content in plaintext YAML files is great if you create the same
2222
types of documents again and again.
2323

24-
Use pdfbaker as a command line tool or Python libary.
24+
Use pdfbaker as a command line tool or Python library.
2525

2626
## When not to use pdfbaker
2727

2828
- When you need something other than PDF
2929
- When flexible document flow is more important than precise positioning
3030

3131
You may want to consider using an Office Suite, HTML/CSS, Markdown or a text-first tool
32-
like LaTex, even if your end result is exported to PDF.
32+
like LaTeX, even if your end result is exported to PDF.
3333

3434
## Advanced features
3535

@@ -44,6 +44,75 @@ like LaTex, even if your end result is exported to PDF.
4444
3. Configure your content and settings in YAML
4545
4. Generate PDFs with `pdfbaker yourconfig.yaml`
4646

47+
Where your SVG had
48+
49+
```xml
50+
<text x="20" y="40" font-family="Arial" font-size="12" fill="#333333">My Document</text>
51+
```
52+
53+
you turn that into
54+
55+
```xml
56+
<text x="20" y="40" font-family="Arial" font-size="12" fill="#333333">{{ title }}</text>
57+
```
58+
59+
and add your custom variable to the YAML configuration:
60+
61+
```yaml
62+
title: "My Document"
63+
```
64+
65+
When you run pdfbaker with your configuration file, `{{ title }}` in your SVG template
66+
will be replaced with the value of `title` from your YAML configuration.
67+
68+
This means you can update your document's content just by editing the YAML file, without
69+
changing the SVG template itself. For guidance on where to place different settings or
70+
variables, see the section ["Inheriting common values"](#inheriting-common-values)
71+
below.
72+
73+
### Quickstart: Create templated PDF from an SVG
74+
75+
Configuring your SVG with YAML requires a main configuration and at least one document
76+
and one page configuration as well as at least one template. Use `--create-from` to set
77+
this all up for an existing SVG file:
78+
79+
1. Design your document in an SVG editor or convert to SVG.
80+
2. Run the following command to scaffold a new project and generate your first PDF:
81+
82+
```bash
83+
pdfbaker --create-from mydesign.svg myproject/myproject.yaml
84+
```
85+
86+
This will create a directory structure like:
87+
88+
```bash
89+
myproject
90+
├── myproject.yaml
91+
└── mydesign
92+
├── config.yaml
93+
├── pages
94+
│   └── main.yaml
95+
└── templates
96+
└── main.svg.j2
97+
```
98+
99+
and produce your PDF in `myproject/dist/mydesign/mydesign.pdf`.
100+
101+
3. Edit the template and YAML files to customize your content and variables. This
102+
directory structure is just a starting point. Add more documents and customize as
103+
needed.
104+
105+
4. For future builds, just run:
106+
107+
```bash
108+
pdfbaker myproject/myproject.yaml
109+
```
110+
111+
to regenerate your PDFs.
112+
113+
See the documentation on [Usage](usage.md) for this and other options that can assist
114+
you.
115+
47116
### From configuration to PDF documents
48117

49118
Your main configuration defines which documents to create.<br>Each document

‎docs/usage.md‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
# Usage - CLI or Library
2+
3+
How to use **pdfbaker** both from the command line and as a Python library.
4+
5+
---
6+
7+
## Command-Line Interface
8+
9+
```bash
10+
$ pdfbaker --help
11+
Usage: pdfbaker [OPTIONS] CONFIG_FILE [DOCUMENT_NAMES]...
12+
13+
Generate PDF documents from YAML-configured SVG templates.
14+
15+
Specify one or more document names to only process those.
16+
17+
Options:
18+
--version Show the version and exit.
19+
-q, --quiet Show errors only.
20+
-v, --verbose Show debug information.
21+
-t, --trace Show trace information (maximum details).
22+
--keep-build Keep rendered SVGs and single-page PDFs.
23+
--debug Debug mode (implies --verbose and --keep-build).
24+
--fail-if-exists Abort if a target PDF already exists.
25+
--dry-run Do not write any files.
26+
--create-from SVG_FILE Scaffold CONFIG_FILE and supporting files for your
27+
existing SVG.
28+
--help Show this message and exit.
29+
```
30+
31+
### Logging verbosity
32+
33+
Use `--quiet` if you only want to see errors, `--verbose` to see the details of what's
34+
getting done, and `--trace` to even see parsed configurations and templates - helpful if
35+
the end result doesn't look right.
36+
37+
### Debugging
38+
39+
If you run into errors or the output doesn't look right, increase log verbosity to see
40+
what's happening and keep intermediary files so you can see how individual page
41+
templates rendered.
42+
43+
Use `--keep-build` to keep the rendered SVGs and PDFs of each page, `--debug` as a
44+
shortcut for "`--verbose` and `--keep-build`".
45+
46+
### Create config from existing SVG
47+
48+
Quickstart! Pass an existing SVG file to `--create-from` and the specified configuration
49+
file and supporting project structure will be created and then processed.
50+
51+
If the path to the (new) config file contains directories that don't exist yet, they
52+
will be created.
53+
54+
For example,
55+
56+
```bash
57+
pdfbaker --create-from poster.svg kiwipycon/kiwipycon.yaml
58+
```
59+
60+
will create a directory `kiwipycon` with a document `poster` that uses a copy of
61+
`poster.svg` as its template:
62+
63+
```bash
64+
kiwipycon
65+
├── kiwipycon.yaml
66+
└── poster
67+
├── config.yaml
68+
├── pages
69+
│   └── main.yaml
70+
└── templates
71+
└── main.svg.j2
72+
```
73+
74+
After this scaffolding, your new document configuration will be processed immediately,
75+
so you'll get a PDF document right away:
76+
77+
```bash
78+
kiwipycon
79+
├── dist
80+
│   └── poster
81+
│   └── poster.pdf
82+
├── kiwipycon.yaml
83+
└── poster
84+
└── ...
85+
```
86+
87+
Next, edit the template and the YAML configuration to replace static content with
88+
variables and set their values. See the [Configuration Reference](configuration.md) for
89+
details.
90+
91+
### Miscellaneous
92+
93+
Use `--dry-run` to parse and process - and therefore validate - your configuration but
94+
not actually write any files. If used in conjunction with `--create-from` this will show
95+
the files that _would_ be created (and will not attempt to process them).
96+
97+
Use `--fail-if-exists` to abort if a target PDF already exists in the "dist" output
98+
folder. This may help you avoid race conditions in automated environments.
99+
100+
Use `--version` to show the installed version of pdfbaker and exit, `--help` to show the
101+
above help text and exit.
102+
103+
---
104+
105+
## Python Library
106+
107+
You can use pdfbaker as a Python library by importing the `Baker` class and configuring
108+
it with `BakerOptions`.
109+
110+
### Example
111+
112+
```python
113+
from pathlib import Path
114+
from pdfbaker.baker import Baker, BakerOptions
115+
116+
options = BakerOptions(
117+
# quiet=False,
118+
# verbose=False,
119+
# trace=False,
120+
# keep_build=True,
121+
# fail_if_exists=False,
122+
# dry_run=False,
123+
# create_from=None,
124+
)
125+
126+
baker = Baker(Path("kiwipycon/poster.yaml"), options=options)
127+
baker.bake()
128+
```

0 commit comments

Comments
 (0)