Open 2bndy5 opened 2 months ago
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>
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: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.