Update README with gif

timvink · timvink · commit dd82961c025c · 2020-05-06T20:51:06.000+02:00
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,43 @@
+# Contribution Guidelines
+
+Thanks for considering to contribute to this project! Some guidelines:
+
+- Go through the issue list and if needed create a relevant issue to discuss the change design. On disagreements, maintainer(s) will have the final word.
+- You can expect a response from a maintainer within 7 days. If you haven’t heard anything by then, feel free to ping the thread.
+- This package tries to be as simple as possible for the user (hide any complexity from the user). New options are only added when there is clear value to the majority of users.
+- When issues or pull requests are not going to be resolved or merged, they should be closed as soon as possible. This is kinder than deciding this after a long period. Our issue tracker should reflect work to be done.
+
+## Unit Tests
+
+Make sure to install an editable version before running the tests:
+
+```python
+pip install -r tests/test_requirements.txt
+pip install -e .
+pytest --cov=mkdocs_git_revision_date_localized_plugin --cov-report term-missing tests/
+```
+
+If it makes sense, writing tests for your PRs is always appreciated and will help get them merged.
+
+In addition, this project uses [pyflakes](https://github.com/PyCQA/pyflakes) for static code checking:
+
+```python
+pip install pyflakes
+pyflakes tests/ mkdocs_git_revision_date_localized_plugin/
+```
+
+## Manual testing
+
+To quickly serve a test website with your latest changes to the plugin use the sites in our tests suite. For example:
+
+```python
+pip install -r tests/test_requirements.txt
+pip install -e .
+mkdocs serve -f tests/fixtures/basic_project/mkdocs.yml
+```
+
+## Code Style
+
+Make sure your code *roughly* follows [PEP-8](https://www.python.org/dev/peps/pep-0008/) and keeps things consistent with the rest of the code.
+
+We use google-style docstrings.
diff --git a/README.md b/README.md
@@ -10,16 +10,16 @@
 
 [MkDocs](https://www.mkdocs.org/) plugin that enables displaying the date of the last git modification of a page. The plugin uses [babel](https://github.com/python-babel/babel/tree/master/babel) and [timeago.js](https://github.com/hustcc/timeago.js) to provide different localized date formats. Initial fork from [mkdocs-git-revision-date-plugin](https://github.com/zhaoterryy/mkdocs-git-revision-date-plugin).
 
-![example](https://github.com/timvink/mkdocs-git-revision-date-localized-plugin/raw/master/example.png)
+![demo](demo_screencast.gif)
 
-(*Example when used together with [mkdocs-material](https://github.com/squidfunk/mkdocs-material) theme*)
+(*Example when used together with the [mkdocs-material](https://github.com/squidfunk/mkdocs-material) theme*)
 
 ## Setup
 
-Install the plugin using `pip` with the following command:
+Install the plugin using `pip3` with the following command:
 
 ```bash
-pip install mkdocs-git-revision-date-localized-plugin
+pip3 install mkdocs-git-revision-date-localized-plugin
 ```
 
 Next, add the following lines to your `mkdocs.yml`:
@@ -32,9 +32,9 @@ plugins:
 
 > If you have no `plugins` entry in your config file yet, you'll likely also want to add the `search` plugin. MkDocs enables it by default if there is no `plugins` entry set.
 
-### When using CI runners
+### Note when using on CI runners
 
-The plugin needs access to the last commit that touched a file to be able to retrieve the date. If you build your docs using CI then you might need to change the default settings:
+The plugin needs access to the last commit that touched a file to be able to retrieve the date. If you build your docs using CI then you might need to change your settings:
 
 - github actions: set `fetch_depth` to `0` ([docs](https://github.com/actions/checkout))
 - gitlab runners: set `GIT_DEPTH` to `1000` ([docs](https://docs.gitlab.com/ee/user/project/pipelines/settings.html#git-shallow-clone))
@@ -45,31 +45,41 @@ The plugin needs access to the last commit that touched a file to be able to ret
 
 ### In supported themes
 
-- [mkdocs-material](https://squidfunk.github.io/mkdocs-material/) offers support for this plugin, see [setup instructions](https://squidfunk.github.io/mkdocs-material/plugins/revision-date/)
+- [mkdocs-material](https://squidfunk.github.io/mkdocs-material/) offers native support for this plugin, see [setup instructions](https://squidfunk.github.io/mkdocs-material/plugins/revision-date/)
 
-### In theme templates
+### In markdown pages
 
-In templates you can use `page.meta.git_revision_date_localized`:
+In your markdown files you can use the `{{ git_revision_date_localized }}` tag anywhere you'd like:
 
 ```django hljs
-{% if page.meta.git_revision_date_localized %}
-  Last update: {{ page.meta.git_revision_date_localized }}
-{% endif %}
+Last update: {{ git_revision_date_localized }}
 ```
 
-### In markdown pages
+### In custom themes
 
-In your markdown files you can use `{{ git_revision_date_localized }}`:
+When writing your own [custom themes](https://www.mkdocs.org/user-guide/custom-themes/) you can use the `page.meta.git_revision_date_localized` jinja tag:
 
 ```django hljs
-Last update: {{ git_revision_date_localized }}
+{% if page.meta.git_revision_date_localized %}
+  Last update: {{ page.meta.git_revision_date_localized }}
+{% endif %}
 ```
 
 ## Options
 
+You can customize the plugin by setting options in `mkdocs.yml`. For example:
+
+```yml
+plugins:
+  - git-revision-date-localized:
+    type: timeago
+    locale: en
+    fallback_to_build_date: false
+```
+
 ### `type`
 
-To change the date format, set the `type` parameter to one of `date`, `datetime`, `iso_date`, `iso_datetime` or `timeago`. Default is `date`. Example outputs:
+Default is `date`. To change the date format, set the `type` parameter to one of `date`, `datetime`, `iso_date`, `iso_datetime` or `timeago`. Example outputs:
 
 ```bash
 28 November, 2019           # type: date
@@ -81,33 +91,16 @@ To change the date format, set the `type` parameter to one of `date`, `datetime`
 
 ### `locale`
 
-Specify a two letter [ISO639](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) language code to display dates in your preferred language.
+Default is `None`. Specify a two letter [ISO639](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) language code to display dates in your preferred language.
 
+- When not set, this plugin will look for `locale` or `language` options set in your theme. If also not set, the fallback is English (`en`)
 - When used in combination with `type: date` or `type: datetime`, translation is done using [babel](https://github.com/python-babel/babel) which supports [these locales](http://www.unicode.org/cldr/charts/latest/supplemental/territory_language_information.html)
 - When used in combination with `type: timeago` then [timeago.js](https://github.com/hustcc/timeago.js) is added to your website, which supports [these locales](https://github.com/hustcc/timeago.js/tree/master/src/lang). If you specify a locale not supported by timeago.js, the fallback is English (`en`)
-- When not set, this plugin will look for `locale` or `language` options set in your theme. If also not set, the fallback is English (`en`)
 
 ### `fallback_to_build_date`
 
-If set to `true` (default is `false`) the plugin will use the time when running `mkdocs build` instead of the git revision date. This means the revision date will be inaccurate, but this can be useful if your build environment has no access to GIT and you want to ignore the Git exceptions during `git log`.
-
-----
-
-### Example
+Default is `false`. If set to `true` the plugin will use the time when running `mkdocs build` instead of the git revision date. This means the revision date will be inaccurate, but this can be useful if your build environment has no access to GIT and you want to ignore the Git exceptions during `git log`.
 
-Example with all options:
+## Contributing
 
-```yaml
-# mkdocs.yml
-plugins:
-  - git-revision-date-localized:
-    locale: en
-    type: timeago
-    fallback_to_build_date: true
-```
-
-Result:
-
-```txt
-20 hours ago
-```
+Contributions are very welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) before putting in any work.
diff --git a/demo_screencast.gif b/demo_screencast.gif
diff --git a/example.png b/example.png
diff --git a/tests/fixtures/demo/docs/index.md b/tests/fixtures/demo/docs/index.md
@@ -0,0 +1,9 @@
+# git-revision-date-localized
+
+A quick demo of adding a last updated date to a MkDocs site
+
+## Installation
+
+```bash
+pip install mkdocs-git-revision-date-localized-plugin
+```
diff --git a/tests/fixtures/demo/docs/one.md b/tests/fixtures/demo/docs/one.md
@@ -0,0 +1,41 @@
+# Lorem Ipsum
+
+## Dolor
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam ut lacus eu elit bibendum luctus ac vel est. Cras lacinia nulla et gravida sodales. Duis ut lorem a mauris accumsan scelerisque eget vel leo. Phasellus dolor ipsum, sagittis ac velit vitae, placerat mattis metus. Nam dictum erat lectus. Sed eget tempus dui. Nulla facilisi. Quisque ut tempus mi. Nunc quis porta felis. In est felis, mattis nec diam sit amet, gravida sollicitudin orci. Suspendisse faucibus pharetra rhoncus. Phasellus orci tellus, interdum in imperdiet quis, ornare et nisi.
+
+## Fusce
+
+Fusce fermentum volutpat metus. Phasellus ut sapien euismod, aliquam enim in, tincidunt augue. In eu pharetra neque. Vestibulum vitae elementum eros, vel ultrices lectus. Sed fermentum mauris sit amet sapien mattis placerat. Curabitur non lorem id dui tincidunt convallis eu non elit. Suspendisse id nibh ut velit facilisis sollicitudin a id nibh. Duis fringilla ante purus, eu maximus enim efficitur quis. Aliquam orci ipsum, rutrum et arcu eu, accumsan luctus odio. Aenean aliquet laoreet erat quis pretium. Vestibulum tincidunt tellus non sagittis aliquam. Nunc aliquam lectus sit amet lacus tempus, vitae aliquet risus viverra. Phasellus volutpat sollicitudin molestie.
+
+## Donec
+
+Donec dignissim dictum molestie. Quisque aliquam nibh elit, in aliquam turpis malesuada sit amet. In eu lectus mi. Etiam mattis viverra libero. Integer ullamcorper condimentum dignissim. Sed eget sapien nec purus aliquet tincidunt. Integer vel ante est. Etiam at dolor nisi. Curabitur id urna sit amet mauris consequat pretium.
+
+## Praesent
+
+Praesent ut congue nisi. Duis sodales magna ac nunc eleifend mollis. Nunc vel gravida nunc. Donec malesuada ligula et venenatis sollicitudin. Integer a condimentum augue, et cursus urna. Fusce vel interdum nisl. Quisque a tempor metus, vitae dapibus mauris. Morbi ultricies bibendum eros a maximus. Nulla lacus urna, ultricies sed convallis sit amet, accumsan at ex. Integer eu maximus metus. Vivamus nec varius mauris. Maecenas efficitur, ligula vehicula lobortis convallis, nisi ex iaculis quam, et convallis purus nisi eget sem. Donec felis elit, convallis et ipsum eu, convallis bibendum risus. Cras ullamcorper, diam dapibus sollicitudin suscipit, est magna fringilla mauris, quis tincidunt ligula magna eget justo.
+
+## Nullam
+
+Nullam pellentesque, nisl sed ullamcorper fermentum, est quam consectetur mi, at porttitor lectus ligula id diam. Curabitur scelerisque pulvinar odio eget iaculis. Quisque commodo non velit non egestas. Sed eleifend nibh at neque condimentum, nec volutpat nulla scelerisque. Nam eget sollicitudin augue. Sed sodales facilisis lacus quis scelerisque. Quisque libero nulla, dictum a urna in, sollicitudin placerat massa. Nam ante mi, interdum ut gravida quis, vestibulum ut risus. Quisque sapien sapien, ultricies ut aliquam non, convallis vitae nunc. Suspendisse et mi a orci finibus volutpat eget eu velit. Cras ac diam tincidunt, porta ligula quis, efficitur neque. Sed cursus sapien vel egestas scelerisque.
+
+## Curabitur
+
+Curabitur eu arcu massa. Maecenas tincidunt tempor dui, vitae sollicitudin diam ornare nec. Nulla sit amet eros fringilla, tincidunt nunc sit amet, sodales nibh. Curabitur id auctor purus. Quisque et venenatis lorem, nec vulputate est. Phasellus molestie enim eget augue dictum, non sagittis massa molestie. In interdum tortor in sapien pretium, eget hendrerit velit scelerisque. Nunc odio tortor, sagittis tincidunt sagittis lobortis, viverra et orci. Maecenas auctor neque nisl, sed commodo quam commodo in. Sed finibus ut nibh commodo porta.
+
+## Fusce
+
+Fusce ullamcorper, erat a sodales commodo, ante mi gravida erat, quis accumsan enim libero et risus. Donec sit amet aliquet dui. Morbi eleifend suscipit nunc, eget elementum sem scelerisque sit amet. Praesent ac ultrices ex, nec volutpat quam. Nunc in felis eget nulla sagittis consequat ac a arcu. Curabitur aliquam vitae sem in ornare. Duis blandit arcu est, sit amet rhoncus erat laoreet ac. Mauris vestibulum euismod urna, vel vestibulum justo fringilla ac. Praesent vitae est sed purus fermentum feugiat. Nullam in auctor nulla. Integer pharetra et eros ac tempus. Duis bibendum vitae metus ac facilisis. Duis sem leo, tempor euismod pharetra in, pharetra id augue. Donec feugiat, mi eget dapibus condimentum, nulla erat viverra lacus, vel aliquam ante arcu et est.
+
+## Nam
+
+Nam vitae urna eget sapien rhoncus pulvinar nec ut lacus. Quisque at massa tempus, varius velit vitae, blandit urna. Morbi consectetur diam at volutpat accumsan. Cras eget porta nisl. Duis vestibulum porta orci, ac hendrerit erat tempor posuere. Quisque commodo fermentum rutrum. Suspendisse sit amet nisl orci. Curabitur fermentum, tellus interdum vulputate iaculis, orci est ornare eros, in convallis ipsum ipsum mollis mauris. Maecenas consequat facilisis magna vitae varius. Sed sagittis sem ac ex fermentum pulvinar. Vestibulum imperdiet interdum nulla, sit amet tempus mi imperdiet in.
+
+## In hac habitasse
+
+In hac habitasse platea dictumst. Quisque in felis gravida, lacinia metus non, placerat elit. Cras eu condimentum urna, id faucibus sapien. Sed vitae risus quis tellus molestie semper at non metus. Sed quis nibh elit. Vestibulum vel leo dapibus, interdum tellus nec, pretium diam. Vivamus eget consequat nisl. Nulla vitae placerat mi. Suspendisse tincidunt non eros eu porta. Morbi sed libero blandit, ullamcorper elit a, suscipit nisi. Nullam libero ante, ultrices non est nec, luctus vestibulum mi. Quisque eu justo in diam dictum vestibulum ut vitae sem. Sed laoreet facilisis mollis.
+
+## Pellentesque 
+
+Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum id sodales nisi. Phasellus id ante vitae mi consequat tempor. Fusce dignissim tortor vitae dolor euismod finibus. Duis malesuada massa eget quam congue, a facilisis arcu feugiat. Donec non neque id risus finibus pretium. Vivamus nisi mauris, scelerisque vitae tortor eu, egestas sagittis lacus. Nunc lobortis, justo id malesuada malesuada, diam dui condimentum dui, sed euismod velit nunc a mauris. Praesent in dictum orci. Mauris varius nisl eget justo mattis malesuada. Mauris mi justo, fermentum a ligula eget, luctus ultricies velit. Cras a condimentum erat. Nulla facilisi.
diff --git a/tests/fixtures/demo/docs/two.md b/tests/fixtures/demo/docs/two.md
@@ -0,0 +1,21 @@
+# Vestibulum
+
+## Sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Fusce condimentum ac nisi ac consequat. Cras condimentum pretium ante in ultrices. Quisque a fermentum dui, nec pellentesque risus. In feugiat, est at scelerisque ultrices, dui lacus tincidunt justo, et dignissim nibh risus in lectus. Cras ut lorem at tellus venenatis lobortis suscipit a justo. Nunc pharetra vitae magna vitae commodo. Sed pulvinar elit ipsum, hendrerit malesuada ex ultricies vel. Sed urna mauris, tincidunt eu rutrum eget, scelerisque sit amet ipsum. Cras bibendum arcu non est condimentum feugiat. Pellentesque dignissim, enim feugiat consectetur tempus, magna justo dapibus erat, in pharetra nulla arcu a sem. Cras non varius velit.
+
+## Lorem Varius
+
+Vestibulum eu lorem varius, malesuada justo et, tempus metus. Proin imperdiet malesuada malesuada. Quisque convallis elementum ipsum vel pretium. Sed non euismod diam. Pellentesque fermentum urna eros, sit amet dignissim odio accumsan id. Curabitur magna magna, accumsan vitae massa at, gravida varius leo. Fusce tellus arcu, aliquam at imperdiet sed, volutpat eu nibh. Aliquam fringilla pellentesque ultricies. Donec placerat fermentum mi, hendrerit vulputate risus blandit eu. Nam pretium urna ac erat euismod, vel faucibus urna efficitur. Nullam risus leo, posuere in elementum at, venenatis vel nisi. Aenean consectetur ultricies massa, sit amet lacinia augue cursus quis. Sed finibus maximus diam at porta. Phasellus tellus massa, rutrum eu consequat quis, interdum vitae metus.
+
+## Maecenas
+
+Maecenas a tincidunt diam. Nulla risus nunc, finibus eget lorem quis, malesuada consectetur sem. Donec auctor nisi justo. Nunc eleifend metus lacus, commodo faucibus sem euismod eget. Nunc ullamcorper tincidunt iaculis. Pellentesque sed augue gravida risus consectetur elementum. Nullam eu dictum ex. Duis at feugiat orci, convallis viverra dui. Curabitur eget lorem ac erat sollicitudin vehicula. Praesent ipsum est, mattis id arcu nec, blandit tristique sapien. Cras tempus porttitor tortor in hendrerit. Cras non quam interdum, molestie diam sed, rutrum purus. In hac habitasse platea dictumst.
+
+## Vivamus
+
+Vivamus volutpat elit non ullamcorper porta. Ut purus erat, pulvinar sit amet fermentum in, tempor non massa. Fusce imperdiet vulputate quam. Nunc viverra porttitor dignissim. Vestibulum id mi vel mi aliquam consectetur. Mauris lectus nulla, rhoncus ullamcorper ultrices quis, semper a orci. Curabitur sapien dolor, maximus et enim eu, pulvinar elementum arcu. Aenean mattis orci sit amet ipsum rhoncus, sit amet fermentum felis sollicitudin. Proin eget augue ac dui condimentum fermentum posuere in turpis. In hac habitasse platea dictumst. Integer a dolor nec orci blandit auctor. Nam turpis sapien, rutrum nec massa eu, interdum euismod magna. Sed et dui suscipit, posuere mi sit amet, tristique arcu. Pellentesque eu diam auctor, hendrerit quam vitae, congue est.
+
+## Aenean
+
+Aenean egestas risus leo, tincidunt fermentum augue rhoncus et. Fusce euismod consequat est. Morbi est justo, fermentum vitae consectetur nec, eleifend ac augue. Fusce tempus arcu sed nibh ornare, quis mattis mauris porta. Proin eget odio consequat, suscipit enim in, hendrerit sapien. Praesent id velit a nulla egestas pellentesque. Sed euismod volutpat venenatis. Suspendisse condimentum sed quam non dictum. Nulla id tincidunt turpis. Duis fermentum venenatis metus. Maecenas quis neque eget ligula convallis ultrices.
diff --git a/tests/fixtures/demo/mkdocs.yml b/tests/fixtures/demo/mkdocs.yml
@@ -0,0 +1,9 @@
+site_name: demo revision date
+use_directory_urls: false
+
+theme:
+    name: material
+
+plugins:
+    - search
+    - git-revision-date-localized
