From 534b51277ae78ac12a1c4415b980bd3477cbbed4 Mon Sep 17 00:00:00 2001 From: Roberto Prevato Date: Sat, 1 Oct 2022 10:15:52 +0200 Subject: [PATCH] Create contribs.md --- docs/contribs.md | 87 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 docs/contribs.md diff --git a/docs/contribs.md b/docs/contribs.md new file mode 100644 index 0000000..895ce1b --- /dev/null +++ b/docs/contribs.md @@ -0,0 +1,87 @@ +The contribs extension provides a plugin to display information about contributors and +last commit time for each page. It works using the `git` CLI to obtain information from +the same repository where the MkDocs site is built. It doesn't require any communication +with third party services, but it requires running in a Git repository. + +!!! danger "Git support only" + This plugin works only with Git repositories, and since it obtains + information from the git repository that contains the MkDocs site, it is + designed for scenarios in which the documentation is built in CI/CD jobs. + +This plugin doesn't require any markup code: it modifies each page to include +contributors' list and last commit time affecting the file, and it doesn't +require integration with any external API. + +## How to use + +Install using `pip install neoteroi-mkdocs`. +Edit your `mkdocs.yml` file to include the extra CSS file from Neoteroi +mkdocs-plugins and the `neoteroi.contribs` plugin for MkDocs: + + +```yaml +extra_css: + - css/neoteroi-mkdocs.css + ... + +plugins: + - search + - neoteroi.contribs +``` + +## Information + +The plugin displays the last modified time for each file (the last time a file +was modified in the Git repository), and the list of contributors, sorted by +commits count. + +![Contribs example](/mkdocs-plugins/img/contribs-01.png) + +## Options + +| Name | Description | Type | Default | +| --------------------- | ------------------------------------------------------------------------- | ------------------------------- | ------------------- | +| `contributors_label` | The label text for contributors list. | `str` | "Contributors" | +| `last_modified_label` | The label text for last modified time. | `str` | "Last modified on" | +| `last_modified_time` | Whether to display the last modified time for each page. | `bool` | `True` | +| `time_format` | Format to be used for dates. | `str` | "%Y-%m-%d %H:%M:%S" | +| `contributors` | Information about contributors, use to configure images for contributors. | `list` of `contributor` objects | `[]` | + +The plugin by default displays dots with the first two initials of each committer's name, +displaying pictures requires explicit configuration, described below. + +### Contributor object + +The following table describes the objects that can be used to provide more +information about contributors. + +| Property | Description | Type | Default | +| -------- | -------------------------------------------- | ----- | ------- | +| `email` | Email address used to match a contributor. | `str` | `n/a` | +| `image` | URL to be used as image for the contributor. | `str` | "" | + +### Including contributors' pictures + +To configure images for contributors, use the `contributors` option like in the +following example: + +```yaml + - neoteroi.contribs: + contributors: + - email: roberto.prevato@gmail.com + image: https://avatars.githubusercontent.com/u/2576032?s=400&u=d8d880e8ed05bb170877dd3d561d8301c4beeeed&v=4 + +``` + +Contributors are matched by email address, and the image is used if configured. + +## Under the hood + +This plugin works by using the following `git` commands, to obtain contributors +and the last modified time of a file: + +``` +git shortlog --summary --numbered --email "README.md" + +git log -1 --pretty="format:%ci" "README.md" +```