It’s 2022. You design a synth module in KiCad 6, and you want to document it. So:
- You open the schematic editor and
- you hit the plot button and plot the schematic to PDF
- you hit the BOM button and choose a BOM format and generate a BOM
- You open the PCB editor and
- you hit the plot button and plot the front silkscreen layer to PDF
- and the back silkscreen layer
- and you figure as long as you’re plotting you might as well export the Gerbers and drill file
- You write up a README.md file
- Except you forget to do one of those until three months later when someone looks at your GitHub repo and says “Hey, why doesn’t the schematic PDF actually match the PCB and why was it created two weeks earlier?”
- Your life is ruined.
- Or maybe you were too lazy to do all of the above and there’s no up to date documentation at all.
It’s 2023. February. You design a synth module in KiCad 7, and you want to document it. But now there’s the kicad-cli command. You can use it to export the schematic PDF. You can use it again to export PCB layout PDFs. And again to export Gerbers. And again to export a netlist, and then you can run a BOM script to read the netlist and generate a BOM.
And galaxy brain that you are, you figure you can write a Linux shell script to automate that, and you do.
It’s 2023. March. You design a synth module in KiCad 7, and you want to document it. But you notice Jordan Aceto has posted a Python script to GitHub. It’s kind of like your shell script, but on steroids. It doesn’t just plot the front and back silkscreen layers to PDF, it plots all the layers — well, most of them. And it plots the front copper and silkscreen and edge cuts to SVG, and likewise back copper and silkscreen and edge cuts to another SVG. It outputs a STEP file, a 3D model of the PCB with components. It outputs an HTML interactive BOM. And it looks a good deal less hacky than your shell script.
Great! you say. Except you want it to behave a little differently — you want maybe a different selection of outputs, or different options to generate the outputs (dark mode for the interactive BOM? Oh, puh-LEASE.), and you want them in differently named folders in a different folder structure. And you want a feature of your shell script which was that it would skip re-generating any output that is newer than the most recent modification of the KiCad file it’s generated from — if you haven’t changed the schematic since the last time you exported the BOM, you don’t need to export the BOM again, right?
About four days later you’ve put way more time into modifying Aceto’s script than you can think of any justification for and it’s at least twice if not three times as many lines of code but it’s doing all kinds of cool things and Aceto’s README now says “NOTE: holmesrichards maintains a much more polished fork of this script”.
It’s called kdocgen.py and it works on Linux, and:
- Unlike your shell script and Aceto’s original, it creates documentation for all the KiCad projects it finds in a main project directory, instead of just the first one.
- Unlike your shell script and Aceto’s original, its behavior is controlled by a bunch of parameters whose default values can be overridden by several layers of configuration files; you can even have different config files for different KiCad projects in the same main project. So you can tell it not to bother putting out a schematic PDF and a BOM for a front panel design, for instance.
- Like your shell script, it doesn’t waste its time regenerating files that don’t need updating.
- It can leverage KiKit to produce separate files for each PCB in a multi-PCB KiCad design. It also allows the choice of using
kicad-clior KiKit to generate Gerbers.
All from a single command on the shell command line. Now you can’t forget to generate the schematic PDF, unless you forget to generate all the documentation. Oh, well, okay, you can disable the schematic PDF in the config file and then forget to re-enable it and not notice it’s not regenerating it. There’s only so much you can do about your absent mindedness. But anyway, it’s a lot easier to generate the documentation, and the Gerbers, so that takes care of the laziness issue.
It’s here:
Analog Output 