Skip to content

Commit 1a6ba58

Browse files
dannyadairdannyadair
committed
feat: Up-to-date documentation
Marking this as a feature to trigger a new release.
1 parent 8efced6 commit 1a6ba58

3 files changed

Lines changed: 51 additions & 39 deletions

File tree

‎docs/configuration.md‎

Lines changed: 18 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -24,23 +24,23 @@ project/
2424

2525
At least `documents` has to be specified.
2626

27-
| Option | Type | Default | Description |
28-
| -------------------------------- | ------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
29-
| `documents` **required** | array | `[]` | List of document configurations. A simple string specifies the name of a directory containing a `config.yaml` file. You can also specify `path` and `name` to a specific configuration YAML file. |
30-
| `directories.base` **read-only** | string | directory containing the config file | Other directories are relative to this base directory. |
31-
| `directories.build` | string | `"build"` | Intermediary SVG and PDF files are written here. Deleted unless `bake` is run with `--keep-build` |
32-
| `directories.dist` | string | `"dist"` | Final PDF files are written here. |
33-
| `directories.documents` | string | `"documents"` | Location of document configurations. |
34-
| `directories.images` | string | `"images"` | Location of image files. |
35-
| `directories.pages` | string | `"pages"` | Location of page configurations. |
36-
| `directories.templates` | string | `"templates"` | Final PDF files are written here. |
37-
| `jinja2_extensions` | array | `[]` | jinja2_extensions (like `jinja2.ext.do`) to load and use in templates. |
38-
| `template_renderers` | array | `["render_highlight"]` | List of automatically applied renderers. `render_highlight` is currently the only available one and enabled by default. It will replace `<highlight>...</highlight>` with `<tspan>` using the colour `style.color` to let you highlight words inside YAML text. |
39-
| `template_filters` | array | `["wordwrap"]` | List of filters made available to templates. `wordwrap` is currently the only available filter. It splits text into lines so that full words have to fit within the specified total number of character for example `{% set desc_lines = item.desc \| wordwrap(40) %}`. |
40-
| `svg2pdf_backend` | string | `"cairosvg"` | Backend to use for SVG to PDF conversion. `"cairosvg"` is built-in, the alternative `"inkscape"` requires Inkscape to be installed |
41-
| `compress_pdf` | boolean | `false` | Whether to compress the final PDF. Requires Ghostscript to be installed. |
42-
| `keep_build` | boolean | `false` | Whether to keep the `build` directory and its intermediary files. You can also pass `bake --keep-build` on individual calls to do this. |
43-
| _additional custom setting_ | | | Any settings you want to make available to all pages of all documents. |
27+
| Option | Type | Default | Description |
28+
| ------------------------------- | ------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
29+
| `documents` **required** | array | `[]` | List of document configurations. A simple string specifies the name of a directory containing a `config.yaml` file. You can also specify `path` and `name` to a specific configuration YAML file. |
30+
| `directories.base` **readonly** | string | directory containing the config file | Other directories are relative to this base directory. |
31+
| `directories.build` | string | `"build"` | Intermediary SVG and PDF files are written here. Deleted unless `bake` is run with `--keep-build` |
32+
| `directories.dist` | string | `"dist"` | Final PDF files are written here. |
33+
| `directories.documents` | string | `"documents"` | Location of document configurations. |
34+
| `directories.images` | string | `"images"` | Location of image files. |
35+
| `directories.pages` | string | `"pages"` | Location of page configurations. |
36+
| `directories.templates` | string | `"templates"` | Location of SVG template files. |
37+
| `jinja2_extensions` | array | `[]` | jinja2_extensions (like `jinja2.ext.do`) to load and use in templates. |
38+
| `template_renderers` | array | `["render_highlight"]` | List of automatically applied renderers. `render_highlight` is currently the only available one and enabled by default. It will replace `<highlight>...</highlight>` with `<tspan>` using the colour `style.color` to let you highlight words inside YAML text. |
39+
| `template_filters` | array | `["wordwrap"]` | List of filters made available to templates. `wordwrap` is currently the only available filter. It splits text into lines so that full words have to fit within the specified total number of character for example `{% set desc_lines = item.desc \| wordwrap(40) %}`. |
40+
| `svg2pdf_backend` | string | `"cairosvg"` | Backend to use for SVG to PDF conversion. `"cairosvg"` is built-in, the alternative `"inkscape"` requires Inkscape to be installed |
41+
| `compress_pdf` | boolean | `false` | Whether to compress the final PDF. Requires Ghostscript to be installed. |
42+
| `keep_build` | boolean | `false` | Whether to keep the `build` directory and its intermediary files. You can also pass `bake --keep-build` on individual calls to do this. |
43+
| _additional custom setting_ | | | Any settings you want to make available to all pages of all documents. |
4444

4545
<details>
4646
<summary>Example Main Configuration File</summary>
@@ -122,7 +122,7 @@ At least `template` has to be specified.
122122
| _any main or document setting_ | | | Any of the Main Configuration File settings can be overridden for a particular document. |
123123
| `template` **required** | string | | Filename of the SVG template (must be in the document's `templates/` directory) |
124124
| `images` | array | | List of images to use in the page. Each image must have a `name` (filename in the document's `images/` directory) and optionally a `type` (defaults to "default") |
125-
| `page_number` **read-only** | integer | | The number of the current page within its document |
125+
| `page_number` **readonly** | integer | | The number of the current page within its document |
126126
| _additional custom setting_ | | | Any settings you want to make available to this page. This allows you to have a template purely for layout purposes. |
127127

128128
<details>

‎docs/custom_processing.md‎

Lines changed: 19 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,33 @@
11
# Custom Processing
22

33
For advanced use cases, you can create a `bake.py` file in your document directory to
4-
customize the document generation process. This allows you to:
5-
6-
- Add custom preprocessing steps
7-
- Modify content dynamically
8-
- Generate content programmatically
9-
- Handle complex document structures
4+
customize the document generation process. This allows you to modify existing and inject
5+
additional settings and content.
106

117
## Basic Structure
128

139
As a naming convention, your `bake.py` needs to define a `process_document` function:
1410

1511
```python
16-
from pdfbaker.document import PDFBakerDocument
17-
18-
def process_document(document: PDFBakerDocument) -> None:
19-
# Custom processing logic here
20-
document.process()
12+
from pdfbaker.document import Document
13+
14+
def process_document(document: Document) -> None:
15+
"""Get settings from other places."""
16+
# Inject additional data into document.config
17+
document.config.profit_and_loss = query_xero_api()
18+
# Continue with regular processing
19+
return document.process()
2120
```
2221

2322
You will usually just manipulate the data for your templates, and then call `.process()`
24-
on the document to continue with the built-in stages of combining pages and compressing
25-
the PDF as configured.
26-
27-
See `examples/custom_processing/bake.py` for a simple example of how to do this.
23+
on the document to continue with the built-in stages of rendering and combining pages as
24+
configured.
2825

2926
If you need to fully customise the processing, make sure that your function returns a
30-
Path or list of Path objects (the PDF files that were created) as that is the expected
31-
type of return value for logging.
27+
single `pathlib.Path` or list of such `Path` objects (the PDF files that were created)
28+
as that is the expected type of return value for logging.
29+
30+
## Example
31+
32+
See [the custom_processing example](../examples/custom_processing) for an implementation
33+
that insert the latest XKCD comic into your PDF.

‎docs/overview.md‎

Lines changed: 14 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -13,15 +13,24 @@ out of the box, it's flexible enough to allow for heavy customisation.
1313
Use SVG to create documents that need precise positioning, complex layouts with
1414
overlapping elements, specific fonts or custom shapes:
1515

16-
- Posters
17-
- Prospectuses
18-
- Fancy reports
16+
- Posters and flyers
17+
- Marketing materials (brochures, prospectuses)
18+
- Fancy reports and certificates
19+
- Any document requiring precise design control
1920

2021
Configuring and editing content in plaintext YAML files is great if you create the same
2122
types of documents again and again.
2223

2324
Use pdfbaker as a command line tool or Python libary.
2425

26+
## When not to use pdfbaker
27+
28+
- When you need something other than PDF
29+
- When flexible document flow is more important than precise positioning
30+
31+
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.
33+
2534
## Advanced features
2635

2736
- [Configuration Reference](configuration.md) - All available settings
@@ -119,4 +128,5 @@ See the [examples](examples) directory:
119128

120129
## Getting Help
121130

122-
- [Open an issue](https://github.com/pythonnz/pdfbaker/issues) on GitHub
131+
If something doesn't work as advertised or is not clearly enough documented, please
132+
[open an issue](https://github.com/pythonnz/pdfbaker/issues) on GitHub.

0 commit comments

Comments
 (0)