docgen: replace doc generation timestamp with version number

[FedericoCeratto]

nim doc inserts a footer in documentation pages e.g. "Made with Nim. Generated: 2020-10-16 08:08:14 UTC "

I suggest replacing it with the (optional) version number for the project the documentation belongs to. The version can be specified as a string using a command line argument.

If nothing is passed, nim doc could adds only "Made with Nim."

This solves 2 problems:

• The documentation can be generate before / during / after a project is released. For users reading the documentation it is difficult to connect the timestamp with the project version or it can be misleading.

• The timestamp makes the build non-reproducible, leading to different artifacts (e.g. tarballs) for the same commit/release, and frequent commits when the documentation is stored in git. See Use SOURCE_DATE_EPOCH instead of current time in docgen #3113

(I'd be happy to send a PR)

[timotheecour]

(I'd be happy to send a PR)

please.
#9073 was very similar but got closed, IMO we should do it, the date is no replacement for commit hash.

version number

too restrictive, a commit hash should be acceptable too

ideally it'd be:

nim doc foo # infer git hash or release tag if we're on tag
nim doc --git.hash:myhash foo # use myhash (eg: 1.2.3) # (or: --git.commit maybe)

and it would display on top (or bottom). This should work for all packages, not just with -d:boot

inferring the git hash or release tag we're at is easy, and nim sources already do that.

see also this thread kaushalmodi/std_vector#6 (comment)

[FedericoCeratto]

I meant "version number" to be a free-form string so that it can contain, for example, a version number, version number + commitish, just the commitish, commitish and branch name... and independent from the VCS in use.
Do we also want additional options to autodetect version / commitish / branch (by executing git)?

[timotheecour]

you can start with just getting the commit hash and we can more later; By default nim doc should show it without having to specify it manually

[juancarlospaco]

const NimblePkgVersion* {.strdefine.} = ""

Should give you the project version number from the nimble file, this is nimble magic.

[timotheecour]

Should give you the project version number from the nimble file, this is nimble magic.

that will be out of date unless no commits were added after last release bump, but we can use both hash + NimblePkgVersion; but note that we can already get latest git tag from git cmdline. This seems the best:
if current hash is at a release tag, only show release tag
else, show both latest release tag + hash

[disruptek]

As long as I don't have to use Nimble to invoke the compiler to generate my documentation, I'm happy.

[Araq]

(I'd be happy to send a PR)

Ok, accepted.