For generated Python pyharp interfaces, add provenance

[Poofjunior]

When we run the generator to create a python pyharp interface, we get:

# This file was automatically generated and should not be edited directly.
# To make changes, edit the device metadata and regenerate the interface.

It would be more useful to add information that includes:

• the CLI command used to generate it
• a link to the utility

Example:

# This file was automatically generated with
#     harp.toolkit.something device.yml --some-flags
# using the generator at:
#     https://github.com/harp-tech/generators/SOMETHING
# Do not edit this file directly. To make changes, edit the device.yml
# and re-run the command above.

For folks new to the ecosystem, they may encounter these generated files in an examples folder for a harp device without any context. It would be useful to point them back to how it was generated so that they can make changes as needed, or go on to build their own devices.

[glopesdev]

@Poofjunior I completely understand the request, the difficulty here is that the generators package is not a CLI tool, but rather a library. This means code can be generated in memory rather than to a file, and the process may not have been initiated by the harp toolkit at all.

I will have a think about this and post here of any updates, but would rather not change the decoupling as we rely on it for unit testing among other things.

[glopesdev]

@Poofjunior an update on this, as promised.

I agree it makes sense to include this at the level of this library, rather than on the toolkit itself, although I will likely not include the exact command. What I'm thinking to include on output file headers is the generator name, its version, maybe a link to this repository, and some or all the identity of the schema the file came from: device name, whoAmI, firmware version and hardware targets. That last part matters for your example, since it tells someone holding an orphaned file not just which device it describes but which schema version produced it. For the C# target the same information also goes into a GeneratedCodeAttribute on the generated types, which is the standard .NET marker, alongside the conventional <auto-generated> comment.

On timing, this is going into the cycle after the next release, mainly because doing it properly means including metadata for all three generator targets rather than Python alone, and the firmware target needs care because some of what it generates is scaffolding that people are expected to fill in by hand, so a blanket instruction not to edit would be wrong there. Embedding a version also means the expected-output tests have to handle a value that differs between local and CI builds. None of this is difficult, but it is not something to rush alongside a release.