Sphinx integration

[FFY00]

A lot of us use sphinx for documentation, it would be cool if we add a direct integration to embed renders, ala populate. I am not sure if that should live here or in a separate repo. I do have interest in helping out with that but the amount of time I will be able to put in will depend on my workload with other projects. For now I am just opening to see if there is interest and to get initial feedback.

[yaqwsx]

This feature would definitely be useful and I would welcome it. However, currently, it is out of my time scope. I will be glad to help, consult, however, I am not sure if I am able to do much coding on this feature in the near future.

[nobodywasishere]

https://github.com/nobodywasishere/sphinx-pcbdraw
It's a work in progress but it's a start. Not sure how to generate it in CI though as there's no KiCAD.

[yaqwsx]

Nice! I will test it later. About KiCAD dependency - you have to either install it in CI or run the build, e.g., KiKit Docker image

[nobodywasishere]

Ah I'm running into #52, and I've tried a lot of stuff and it's not working. I can't use the KiKit docker image directly as I'm also using a sphinx docker image for building, and so I either have to install kikit/kicad on the sphinx docker image, or install sphinx in the kikit docker image. I've tried the former here. Any recommendations?

[yaqwsx]

I looked at your action specification and I miss the actual Sphinx invocation. What exactly fails? Als, the action seems to pass with no error (though, it does not invoke Sphinx)

[nobodywasishere]

The sphinx action is called within ammaraskar/sphinx-action.
Also the error location is here.
I catch the error and put an error node in it's place (so it'll compile with warnings). See here.

[nobodywasishere]

I got it working. I ended up installing everything into the VM itself rather than using Docker. Now time for iterative improvements!

[nobodywasishere]

I think there should be a --hidden comma,seperated,list command-line option added to PcbDraw (if it doesn't already exist) that will hide said components from the final design. This would be useful, for example, hiding pin headers.

For the pcbdraw directive, I think it should look something like this:

.. pcbdraw:: path/to/pcb.kicad_pcb
   :style: path/to/style.json           # select a path/to/style.json
                                        # or selects a builtin style if not a proper path
   :placeholder:                        # place red squares in place of missing components
   :remap: path/to/remap.json           # use path/to/remap.json to remap components
   :no-drillholes:                      # don't make drillholes transparent
   :back:                               # draw the back of the board
   :mirror:                             # mirror board on x-axis
   :highlight: comma, separated, list   # highlight these components
   :filter: comma, separated, list      # only show these components
   :hidden: comma, separated, list      # don't show these components

There should also be some global configurations for conf.py:

sphinx_pcbdraw_libs = ["lib/folder/one", "lib/folder/two"] # library folders to include for generation
sphinx_pcbdraw_style = "path/to/style.json" # default style path or builtin
sphinx_pcbdraw_remap = "path/to/remap.json" # default for remapping components
sphinx_pcbdraw_hidden = ["component1", "component2"] # list of components to hide from all designs

Thoughts?

[yaqwsx]

Well, I think PcbDraw would benefit from a rewrite from scratch. I have it somewhere on my roadmap once KiCAD 6 will be released.

There is the filter option:

PcbDraw/pcbdraw/pcbdraw.py

Line 716 in 3b96105

parser.add_argument("-a", "--highlight", help="comma separated list of components to highlight")

[nobodywasishere]

Made some updates, adding the directive options and adding another directive for creating a table of the list of components. See the github repo and the website. There's probably a better way of doing this stuff (I'm still getting a handle on Sphinx) but this should work.

I could probably help with a PcbDraw rewrite whenever you start it. Writing it as a shared library / class with a command-line wrapper would make it so sphinx-pcbdraw could use it directly instead of having to call subprocess as well.

[perigoso]

kicad is a hard requirement right? no way around it?
I was working on using pcbdraw on a projects documentation, but i would need it to work on readthedocs, where i think its onlyn possible to install python dependencies.

[FFY00]

Technically, you could package kicad as a Python package, but that'd be a bit hacky 😅

[yaqwsx]

KiCAD is a hard requirement as we avoid interpreting the KiCAD files directly and we use KiCAD to interpret it. In this way, the implementation is much simpler and also, always correct (regarding added KiCAD features, etc.)

[perigoso]

Technically, you could package kicad as a Python package, but that'd be a bit hacky sweat_smile

my first thought lol

that said, maybe only the pcbnew component and the python binding is possible? id hate to do it but if it works it works

[yaqwsx]

@FFY00: FYI I started rewriting PcbDraw such that it can be used as a library (and also the code is refactored, so new features are easier to add). I started in fead173. I expect that the basic plotter interface won't change much towards v1.