I have a weird thing with the multiplication of command-line tools and gizmos: I forget them.
Do I want to run supercool gitlab commands? Hell yea! Do I need to install 12 utilities (or code a new one) to archive every project older than a year? I hope not...
I am a sucker for well documented fully linted code. But the thing is, all the gizmos that help me do that have to be installed in the system or in my
~/bin and I have to remember to update them, and I have to install them on my CD machine, and on every new environment I setup, and make sure they are still compatible with the toolchain, and it freaks me out, ok?
Plus,watching the students try to do it is painful.
So, given a 100% vanilla swift-capable environment, can I manage to run documentation and linting?
We have Swift Package Manager, which is now a first-class citizen in XCode, but it can't run shell script phases without some nasty hacks.
What if some targets were (wait for it) built to do the documentation and the linting?
One of the most popular linters out there is swiftlint, and it supports SPM. It can also build a library instead of an executable, which means one of my targets could just run the linting and output it in the terminal.
Package.swift file, all I needed to do was add the right dependency, and the right product and voila!
Now, SPM is very strict with paths, so I had to put a file named
main.swift in the
Sources/<target>/ directory, in this case
Running the linter is fairly straightforward, and goes in the
.swiftlint file as usual, and run the command via
swift run Lint
Sources/WonderfulPackage/main.swift ⛔️ Line 15: Variable name should be between 3 and 40 characters long: 'f' ⚠️ Line 13: Arguments can be omitted when matching enums with associated types if they are not used. ⚠️ Line 12: Line should be 120 characters or less: currently 143 characters
Documentation is actually trickier, because most documentation tools out there aren't built in swift, or compatible with SPM. Doxygen and jazzy are great, but they don't fit my needs.
I found a project that was extremely promising called SourceDocs by Eneko Alonso, but it isn't a library, so I had to fork it and make it into one (while providing a second target to generate the executable if needed). One weird issue is that SPM doesn't like subtargets to bear the same name so I had to rename a couple of them to avoid conflict with Swift Argument Parser (long story).
I finally found myself in the same spot than with the linter. All I needed to do was create another target, and Bob's you're uncle. Well actually he was mine. I digress.
Another well-placed main file:
Now, the command
swift run Docs generates the markdown documentation in the
Parsing main.swift (1/1) Removing reference documentation at 'WonderfulPackage/Documentation/KituraStarter'... ✔ Generating Markdown documentation... Writing documentation file: WonderfulPackage/Documentation/WonderfulPackage/structs/WonderfulPackage.md ✔ Writing documentation file: WonderfulPackage/Documentation/WonderfulPackage/README.md ✔ Done 🎉 Successful run of the documentation phase
✅ Vanilla swift environment
✅ No install needed
✅ Works on Linux and MacOS
✅ Integrated into SPM
⚠️ When running in XCode, the current directory is always wonky for packages