Add swift-doc version number to generated footers

[mattt]

The quick-and-dirty way to do this would be to hard-code a top-level version constant, but that would require a manual (and therefore error-prone) process of updating it for every release.

A better solution would be to pull this information from git during the build process (maybe using GYB?).

Even better would be if the Swift Package Manager had a way to generate these symbols at build time. Does anyone know if this is currently possible? And if not, what do you think about requesting this through Swift Evolution?

[mattt]

.@natecook1000 recently added support for a --version flag to ArgumentParser.

apple/swift-argument-parser#102

Given the existence of an official standard for where this information goes, I'm happy to manually update this string as part of the release process.

[MaxDesiatov]

Throwing ideas around, in the ideal world I wish we could see swift-doc allowing users to switch between multiple versions of generated documentation. To clarify the use case, I'd like to publish documentation for multiple versions, the latest version is displayed by default, but a user can select a different version in a dropdown (or whatever control is provided by the theme). Switching to an old version would display a warning reminding they can switch to the latest version, similar to what Scikit-learn documentation is doing.

Even more ambitiously, it could generate API diffs between versions 🤩

[mattt]

You've touched on something central to the "big picture" for SwiftDoc. Software documentation shouldn't be limited to static information rendered in HTML. It should be a living autobiography developed alongside the code it represents — one that's versioned, semantic, queryable, testable, and made accessible in a variety of formats.

Right now, I'm trying to strike the right balance between incremental, short-term wins vs. articulating and developing long-term vision. Having something palpable like HTML output goes a long way to getting folks excited and involved long-term, while also providing short-term benefit by solving an immediate problem, so that's my focus right now. But yeah, I'm excited to start teasing out some details about the "big picture" stuff, and would very much appreciate your continued input about the direction of everything 😄