kmk_firmware
kmk_firmware copied to clipboard
KMKfw
Add docstrings to classes and methods throughout the codebase
Adding docstrings would improve the developer experience for contributors given the extensive support for them in popular modern editors such as PyCharm and Visual Studio Code. Even without the integrations those offer, having them there is beneficial to anyone reading through the code.
It would, but keep in mind that we're developing for embedded systems and docstrings occupy quite a bit of memory, which is already tight on certain platforms. As KMKs functional code base is growing, there may come a point in time at which we have to strip down docstrings again, or lose the ability to copy-paste the code to devices and have to fall back to a less userfriendly toolchain.
One solution would be to have an automated build step that pulls out comments and docstrings (should be fairly simple using a bash script with sed), then segregate the source and distribution files.
The same could be done with type annotations using something like strip-hints, or, again, with sed.
P.S.: this is not a critique of good comments and docstrings btw, just something we have to consider in the long run.
sed isn't the right tool for that, you'd want a proper parser, and at that point we might as well depend on mpy_cross.
The "problem" is that it complicates the process. Personally, I'm very comfortable with using a build toolchain or whatever, but that does not necessarily speak for the average KMK user. The copy-paste installation of KMK and ability to edit directly on the CP drive is something that sets KMK apart from other more low-level firmware projects, and there's a lot of people who appreciate that.
sidenote: this topic is distantly related to #513.
An already-minified and/or compiled version could be provided alongside the full-fat version, letting the end user decide which to use. In that case, the build process would happen on the CI/CD end, not the user's end, and can be automated through GitHub actions.
I agree that the ability to live edit is one of KMK's strongest selling points - that's why I've swapped to it from QMK, in fact.
Long, long ago, we actually had zip files published in a CI loop from master (to cdn.kmkfw.io, a DigitalOcean Spaces bucket with HTTPS access abilities), one was the raw .py files, the other was the output of make compile. At various points our CI-related dependencies bitrotted, I left KMK for the most part, and we moved from CircleCI to GitHub Actions, and those CI jobs failed, were removed, and the zip links removed from the README.
Until @xs5871's comment on #513 I'd kinda forgotten that makefile job ever existed, but it jogged my memory that we indeed used to ship this stuff.
Circuitpython is also very picky about the mpy_cross version. At multiple times in the past I couldn't even get the official releases to play nicely with one another and had to compile mpy_cross myself. May not be an issue anymore.
With pre-compiled code we can only support a specific CP version, or at most a narrow range of versions.
As much as we don't want to tie into github, if anyone wants to step up and create auto builds, even with github actions, we'd probably be willing to accept that. We have ties to github at this point, but the code still doesn't rely on github to exist. Compromises can be made if no one else wants to step up and offer an option that doesn't rely on GH.
