Support updating text variables in .kicad_pcb file explicitly

[matthijskooijman]

Normally, the text variables in the .kicad_pcb file are cleared when requested, or when changing them with the set_text_variables preflight. This causes KiCad to load the variables from the project file when opening the PCB, but this does not work when the .kicad_pcb file is used in isolation (e.g. when submitting to a PCB manufacturer).

This commit adds support for invalidate_pcb_text_cache=update, which causes kibot to explicitly write the (updated / current) variables to the .kicad_pcb file, making it self-contained.

This fixes #860

[matthijskooijman]

(force pushed to fix typo)

I've submitted this as a draft, since I am not entirely convinced that my approach of adding a new 'update' value to the existing invalidate_pcb_text_cache config directive is the best approach, for two reasons: 1) the config is about invalidating cache, not updating it, which might be a bit weird and 2) this now only works when requesting update explicitely, so there is no way to express "update them only when changed by set_text_variables", like the current auto value does (which is changed to yes by set_text_variables.

I'm not sure what the best approach would be, maybe also add an auto_update value (that can be changed to update by set_text_variables), or deprecate invalidate_pcb_text_cache and add a new value like update_pcb_text_cache=no/clear/update/auto_clear/auto_update, or maybe split into two config directives? Or maybe just make this the default and only behavior? Let me know your thoughts.

Even with the above caveats, I wanted to submit this PR to demonstrate that the approach itself works as expected (tested locally by copying the updated files into a kibot docker container).

[set-soft]

What about a new, and independent, global option update_pcb_text_cache with no|yes as options.
And handle it separately.
It could even have an auto option that becomes yes when using set_text_variables.
So we get all the combinations without changing the current options, just adding more.

[matthijskooijman]

That sounds like a good approach, I've just implemented this, including the 'auto' option. I'm marking this PR as non-draft, AFAICS it would be ready to review and merge.

There is one (existing) caveat that I ran into: There is a restore_project option that is intended to undo any changes to the project file, in particular made by the set_text_variables preflight. However, that does not undo the changes to the PCB file, as made by invalidate_pcb_text_cache (and now also update_pcb_text_cache. This is not a big deal for me, as I am mostly using kibot in CI, so lingering changes are not problematic, but maybe this is something to fix separately.

[set-soft]

There is one (existing) caveat that I ran into: There is a restore_project option that is intended to undo any changes to the project file, in particular made by the set_text_variables preflight. However, that does not undo the changes to the PCB file, as made by invalidate_pcb_text_cache (and now also update_pcb_text_cache. This is not a big deal for me, as I am mostly using kibot in CI, so lingering changes are not problematic, but maybe this is something to fix separately.

I think people that wants to avoid changes should disable the invalidate_pcb_text_cache and update_pcb_text_cache. The restore_project applies to the kicad_pro file.

[set-soft]

Can you rebase this PR to the dev branch?
I can merge it as-is, but it won't be attributed to you.

Also: you don't need to include changes to docs/source/configuration/sup_globals.rst they are automatically generated.

[matthijskooijman]

Can you rebase this PR to the dev branch?

Done, though I did not do any additional testing with the rebased version (no time right now).

Also: you don't need to include changes to docs/source/configuration/sup_globals.rst they are automatically generated.

Ah, I dropped those changes.

When are they autogenerated? When building the docs with the Makefile, it seems? If so, why is the file present in git at all? Might be cleaner to not have it than carry an outdated version around?

[set-soft]

When are they autogenerated? When building the docs with the Makefile, it seems?

Yes, make doc

If so, why is the file present in git at all?

Mainly because you need a working KiBot to generate them, which isn't always true. The requirements to generate the HTML files are relaxed in this way

Might be cleaner to not have it than carry an outdated version around?

They are synced very often, the doc target generates a lot of stuff.