add extension for supplementing git stats about doc sources

[2bndy5]

As of upstream v4.6.0, there has been support for getting the doc source creation time via git (using a mkdocs plugin). Additionally, there was support added in v9.5.0 for fetching the document source contributors/authors via git (using another mkdocs plugin).

My hunch is that this can all be done at build time using a library that either interacts with the git executable (GitPython) or directly with the .git data (pygit2 for example). I would prefer using pygit2, but installing that C-extension may prove problematic in some build systems (SSL certs and CFFI/Python C API headers are required).

I am concerned that a shallow checkout would prevent getting sufficient (& correct) information because github's actions/checkout does not fetch the entire history unless explicitly told.

Of course this can all be done using subprocess.run(['git', ...]) for each document. I have a one-liner to get relative file creation time:

$ git log --format="%ar" --diff-filter="A" docs/graphviz.rst
1 year, 7 months ago

The result can be fed into the HTML template's page['meta']['git_creation_date_localized'] value. But it would be better to use a git-based library to extract info from the checked out repo. This would be more beneficial to aggregating git contributors/authors as well.

PS - All of this git info would be cached, of course, to prevent prolonged build times.

[2bndy5]

I have also considered using Sphinx' codeauthors and sectionauthors directives (which supplement a page's metadata). But it would much more convenient to programmatically get this info instead of relying on (and adding to) a project's contributor requirements.

Setting show_authors in conf.py produces the following HTML output:

<p>
<em>Code author: Brendan <
  <a class="reference-external" href="mailto:emal%40address.com">
    email<span>@</span>address<span>.</span>com
  </a>
>
</em>
</p>