132 lines
4.1 KiB
Markdown
132 lines
4.1 KiB
Markdown
# Populate
|
|
|
|
Populate allows you to write a simple population guide for you board in markdown
|
|
and automatically convert to either a webpage with images or a markdown files
|
|
with images suitable for GitHub wiki.
|
|
|
|
It allows you to write text, incrementally add new components to the board and
|
|
highlight newly added components.
|
|
|
|
The core code for this tool comes from the [PcbDraw project](https://github.com/yaqwsx/PcbDraw/).
|
|
This documentation is adapted from the original project.
|
|
|
|
|
|
## Usage
|
|
|
|
You must define a `populate` type output, and this output must indicate how to
|
|
draw the steps using a `pcbdraw` type output. The name of the output using to
|
|
draw is indicated in the `renderer` option. So you need to define at least
|
|
two outputs, i.e.:
|
|
|
|
```yaml
|
|
kiplot:
|
|
version: 1
|
|
|
|
outputs:
|
|
- name: PcbDraw
|
|
comment: "How to draw a step"
|
|
type: pcbdraw
|
|
run_by_default: false
|
|
options:
|
|
format: png
|
|
|
|
- name: Populate
|
|
comment: "Populate example"
|
|
type: populate
|
|
dir: Populate
|
|
options:
|
|
renderer: PcbDraw
|
|
input: tests/data/plain_html.md
|
|
```
|
|
|
|
When using the `populate` command from the `pcbdraw` project all the options
|
|
to render the images is contained in the input markdown file
|
|
(`tests/data/plain_html.md` in the above example). When using KiBot all the
|
|
information comes from the KiBot configuration file, and the YAML text from
|
|
the input markdown file is discarded.
|
|
|
|
You can try the above example using the following
|
|
[PCB example](../tests/data/ArduinoLearningKitStarter.kicad_pcb).
|
|
From the root of the KiBot repository you can run:
|
|
|
|
```shell
|
|
src/kibot -c tests/yaml_samples/populate_simple.kibot.yaml -b tests/data/ArduinoLearningKitStarter.kicad_pcb -d example
|
|
```
|
|
|
|
Then load the generated web page: `example/PopulateSimple/index.html`
|
|
|
|
|
|
## Source file format
|
|
|
|
The source file format is a simple markdown file with two specialties -- each
|
|
list item is considered as a single step in populating and will generate an
|
|
image. The content of the item is the step description. See
|
|
[example](../tests/data/plain_html.md).
|
|
|
|
**Note**: list items without an explicit step will be processed as regular list items.
|
|
Avoid mixing regular list items and steps in the same list.
|
|
|
|
To specify which side of the board and which components to add and highlight start the item with a clause in form:
|
|
|
|
```
|
|
- [[<front|back> | <comma separated list of components to add> ]]
|
|
```
|
|
|
|
For example:
|
|
|
|
- `[[front | R1,R2 ]]` will render front side of the board and adds R1 and R2.
|
|
- `[[back | ]]` will render the back side and no components will be added
|
|
|
|
Note that KiBot also allows to include groups of components selected by a filter.
|
|
If you use `[[front | R1,_kf(all_smd) ]]` and you have the following filter:
|
|
|
|
```yaml
|
|
- name: all_smd
|
|
type: generic
|
|
exclude_smd: true
|
|
invert: true
|
|
```
|
|
The list will be expanded to R1 plus all the SMD components of the board.
|
|
But suppose you want to select all the SMD components of the top side of the board,
|
|
you could use `[[front | _kf(all_smd;all_front) ]]` adding the following filter:
|
|
|
|
```yaml
|
|
- name: all_front
|
|
type: generic
|
|
exclude_bottom: true
|
|
```
|
|
|
|
Note that we use `;` as separator because `,` is the separator in the list of references.
|
|
You can also use the `!` (not) operator, like this: `[[front | _kf(all_tht;!all_conn) ]]`
|
|
This will select all THT components that aren't connectors, assuming you provide the
|
|
correct filters. Here is an [example to try](../tests/data/with_filter_html.md).
|
|
|
|
## Handlebars template
|
|
|
|
To specify HTML output you can use a [Handlebar](https://handlebarsjs.com/)
|
|
template. The template is fed with a data structure like this:
|
|
|
|
```{.json}
|
|
{
|
|
"items": [
|
|
{
|
|
"type": "comment",
|
|
"is_comment": true,
|
|
"content": "Generated HTML from markdown of the comment"
|
|
},
|
|
{
|
|
"type": "step",
|
|
"is_step": true,
|
|
"steps": [
|
|
{
|
|
"img": "path to generated image",
|
|
"comment": "Generated HTML from markdown of the comment"
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
There can be multiple `step` and `comment` sections.
|