Skip to content

Commit b529282

Browse files
authored
Merge pull request #45 from RDIL/master
Several enhancements
2 parents baa45ce + c468771 commit b529282

File tree

12 files changed

+101
-65
lines changed

12 files changed

+101
-65
lines changed

.flake8

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
[flake8]
2+
ignore = E501,E722

CONTRIBUTING.md

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -11,9 +11,12 @@ Thanks for considering to contribute to this project! Some guidelines:
1111

1212
There are multiple mkdocs plugins that use information from the local git repo.
1313

14-
In order to simplify user experience and maintenance, I intend to merge functionality in this plugin with [mkdocs-git-authors-plugin](https://github.com/timvink/mkdocs-git-authors-plugin). See https://github.com/timvink/mkdocs-git-authors-plugin/issues/16 for a similar roadmap issue with more details.
14+
In order to simplify user experience and maintenance,
15+
I intend to merge functionality in this plugin with [mkdocs-git-authors-plugin](https://github.com/timvink/mkdocs-git-authors-plugin).
16+
See https://github.com/timvink/mkdocs-git-authors-plugin/issues/16 for a similar roadmap issue with more details.
1517

16-
That means not extending the functionality of this plugin, but rather aiming to create a simple, stable release that can go into 'maintenance mode'. If users want more information extracted from GIT, they can go to [mkdocs-git-authors-plugin](https://github.com/timvink/mkdocs-git-authors-plugin).
18+
That means not extending the functionality of this plugin, but rather aiming to create a simple, stable release that can go into 'maintenance mode'.
19+
If users want more information extracted from Git, they can go to [mkdocs-git-authors-plugin](https://github.com/timvink/mkdocs-git-authors-plugin).
1720

1821
## Unit Tests
1922

@@ -27,7 +30,7 @@ pytest --cov=mkdocs_git_revision_date_localized_plugin --cov-report term-missing
2730

2831
If it makes sense, writing tests for your PRs is always appreciated and will help get them merged.
2932

30-
In addition, this project uses [pyflakes](https://github.com/PyCQA/pyflakes) for static code checking:
33+
In addition, this project uses [flake8](https://github.com/PyCQA/flake8) for static code checking:
3134

3235
```python
3336
pip install pyflakes
@@ -36,7 +39,8 @@ pyflakes tests/ mkdocs_git_revision_date_localized_plugin/
3639

3740
## Manual testing
3841

39-
To quickly serve a test website with your latest changes to the plugin use the sites in our tests suite. For example:
42+
To quickly serve a test website with your latest changes to the plugin use the sites in our tests suite.
43+
For example:
4044

4145
```python
4246
pip install -r tests/test_requirements.txt
@@ -46,6 +50,7 @@ mkdocs serve -f tests/fixtures/basic_project/mkdocs.yml
4650

4751
## Code Style
4852

49-
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.
53+
Make sure your code *roughly* follows [PEP-8](https://www.python.org/dev/peps/pep-0008/)
54+
and keeps things consistent with the rest of the code.
5055

51-
We use google-style docstrings.
56+
We use Google-style docstrings.

MANIFEST.in

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,2 @@
11
include mkdocs_git_revision_date_localized_plugin/js/*.js
2-
include mkdocs_git_revision_date_localized_plugin/css/*.css
2+
include mkdocs_git_revision_date_localized_plugin/css/*.css

mkdocs_git_revision_date_localized_plugin/ci.py

Lines changed: 26 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -2,13 +2,13 @@
22
import logging
33

44

5-
def raise_ci_warnings(repo):
5+
def raise_ci_warnings(repo) -> None:
66
"""
7-
raise warnings when users use mkdocs-git-revision-date-localized-plugin
8-
on CI build runners
7+
Raise warnings when users use mkdocs-git-revision-date-localized-plugin
8+
on CI build runners.
99
1010
Args:
11-
repo (GitPython.git.repo): The Git repo object
11+
repo (GitPython.git.repo): The Git repo object.
1212
"""
1313

1414
if not is_shallow_clone(repo):
@@ -17,36 +17,39 @@ def raise_ci_warnings(repo):
1717
n_commits = commit_count(repo)
1818

1919
# Gitlab Runners
20-
if os.environ.get("GITLAB_CI") and n_commits < 50:
20+
if os.getenv("GITLAB_CI") is not None and n_commits < 50:
2121
# Default is GIT_DEPTH of 50 for gitlab
2222
logging.warning(
2323
"""
24-
[git-revision-date-localized-plugin] Running on a gitlab runner might lead to wrong git revision dates
25-
due to a shallow git fetch depth.
26-
Make sure to set GIT_DEPTH to 1000 in your .gitlab-ci.yml file.
24+
[git-revision-date-localized-plugin] Running on a GitLab runner might lead to wrong
25+
Git revision dates due to a shallow git fetch depth.
26+
27+
Make sure to set GIT_DEPTH to 1000 in your .gitlab-ci.yml file
2728
(see https://docs.gitlab.com/ee/user/project/pipelines/settings.html#git-shallow-clone).
2829
"""
2930
)
3031

3132
# Github Actions
32-
if os.environ.get("GITHUB_ACTIONS") and n_commits == 1:
33+
if os.getenv("GITHUB_ACTIONS") is not None and n_commits == 1:
3334
# Default is fetch-depth of 1 for github actions
3435
logging.warning(
3536
"""
36-
[git-revision-date-localized-plugin] Running on github actions might lead to wrong git revision dates
37-
due to a shallow git fetch depth.
38-
Try setting fetch-depth to 0 in your github action
37+
[git-revision-date-localized-plugin] Running on GitHub Actions might lead to wrong
38+
Git revision dates due to a shallow git fetch depth.
39+
40+
Try setting fetch-depth to 0 in your GitHub Action
3941
(see https://github.com/actions/checkout).
4042
"""
4143
)
4244

4345
# Bitbucket pipelines
44-
if os.environ.get("CI") and n_commits < 50:
46+
if os.getenv("CI") is not None and n_commits < 50:
4547
# Default is fetch-depth of 50 for bitbucket pipelines
4648
logging.warning(
4749
"""
48-
[git-revision-date-localized-plugin] Running on bitbucket pipelines might lead to wrong git revision dates
49-
due to a shallow git fetch depth.
50+
[git-revision-date-localized-plugin] Running on bitbucket pipelines might lead to wrong
51+
Git revision dates due to a shallow git fetch depth.
52+
5053
Try setting "clone: depth" to "full" in your pipeline
5154
(see https://support.atlassian.com/bitbucket-cloud/docs/configure-bitbucket-pipelinesyml/
5255
and search 'depth').
@@ -55,26 +58,27 @@ def raise_ci_warnings(repo):
5558

5659
# Azure Devops Pipeline
5760
# Does not limit fetch-depth by default
58-
if os.environ.get("Agent.Source.Git.ShallowFetchDepth", 10e99) < n_commits:
61+
if int(os.getenv("Agent.Source.Git.ShallowFetchDepth", 10e99)) < n_commits:
5962
logging.warning(
6063
"""
61-
[git-revision-date-localized-plugin] Running on Azure pipelines with limited fetch-depth might lead to wrong git revision dates
62-
due to a shallow git fetch depth.
64+
[git-revision-date-localized-plugin] Running on Azure pipelines with limited
65+
fetch-depth might lead to wrong git revision dates due to a shallow git fetch depth.
66+
6367
Remove any Shallow Fetch settings
6468
(see https://docs.microsoft.com/en-us/azure/devops/pipelines/repos/pipeline-options-for-git?view=azure-devops#shallow-fetch).
6569
"""
6670
)
6771

6872

69-
def commit_count(repo) -> bool:
73+
def commit_count(repo) -> int:
7074
"""
71-
Helper function to determine the number of commits in a repository
75+
Helper function to determine the number of commits in a repository.
7276
7377
Args:
74-
repo (GitPython.Repo.git): Repository
78+
repo (GitPython.Repo.git): Repository.
7579
7680
Returns:
77-
count (int): Number of commits
81+
count (int): Number of commits.
7882
"""
7983
refs = repo.for_each_ref().split("\n")
8084
refs = [x.split()[0] for x in refs]
Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
11
/*
2-
timeago output is dynamic, which breaks when you print a page
3-
This ensures fallback to type "iso_date" when printing
4-
*/
2+
* timeago output is dynamic, which breaks when you print a page.
3+
* This ensures fallback to type "iso_date" when printing.
4+
*/
55

66
.git-revision-date-localized-plugin-iso_date { display: none }
77

88
@media print {
99
.git-revision-date-localized-plugin-iso_date { display: inline }
1010
.git-revision-date-localized-plugin-timeago { display: none }
11-
}
11+
}

mkdocs_git_revision_date_localized_plugin/js/timeago_mkdocs_material.js

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,14 +4,14 @@
44
if (
55
typeof app !== "undefined" &&
66
typeof app.document$ !== "undefined"
7-
) {
7+
) {
88
app.document$.subscribe(function() {
99
var nodes = document.querySelectorAll('.timeago');
1010
var locale = nodes[0].getAttribute('locale');
1111
timeago.render(nodes, locale);
1212
})
1313
} else {
14-
var nodes = document.querySelectorAll('.timeago');
15-
var locale = nodes[0].getAttribute('locale');
16-
timeago.render(nodes, locale);
17-
}
14+
var nodes = document.querySelectorAll('.timeago');
15+
var locale = nodes[0].getAttribute('locale');
16+
timeago.render(nodes, locale);
17+
}

mkdocs_git_revision_date_localized_plugin/plugin.py

Lines changed: 17 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -12,17 +12,21 @@
1212
# package modules
1313
from mkdocs_git_revision_date_localized_plugin.util import Util
1414

15+
from typing import Any, Dict
16+
1517
HERE = os.path.dirname(os.path.abspath(__file__))
1618

19+
1720
class GitRevisionDateLocalizedPlugin(BasePlugin):
1821
config_scheme = (
1922
("fallback_to_build_date", config_options.Type(bool, default=False)),
2023
("locale", config_options.Type(str, default=None)),
2124
("type", config_options.Type(str, default="date")),
2225
("timezone", config_options.Type(str, default="UTC")),
26+
("excluded_page_titles", config_options.Type(list, default=[]))
2327
)
2428

25-
def on_config(self, config: config_options.Config, **kwargs) -> dict:
29+
def on_config(self, config: config_options.Config, **kwargs) -> Dict[str, Any]:
2630
"""
2731
Determine which locale to use.
2832
@@ -121,6 +125,12 @@ def on_page_markdown(
121125
str: Markdown source text of page as string
122126
"""
123127

128+
excluded_titles = self.config.get("excluded_page_titles", [])
129+
if page.title in excluded_titles:
130+
logging.debug("Excluding page " + page.url)
131+
# page is excluded
132+
return markdown
133+
124134
revision_dates = self.util.get_revision_date_for_file(
125135
path=page.file.abs_src_path,
126136
locale=self.config.get("locale", "en"),
@@ -143,12 +153,14 @@ def on_page_markdown(
143153
flags=re.IGNORECASE,
144154
)
145155

146-
147-
def on_post_build(self, config, **kwargs):
148-
156+
def on_post_build(self, config: Dict[str, Any], **kwargs) -> None:
157+
"""
158+
Run on post build.
159+
Adds the timeago assets to the build.
160+
"""
149161
# Add timeago files:
150162
if self.config.get("type") == "timeago":
151-
files = ['js/timeago.min.js', 'js/timeago_mkdocs_material.js', 'css/timeago.css']
163+
files = ["js/timeago.min.js", "js/timeago_mkdocs_material.js", "css/timeago.css"]
152164
for file in files:
153165
dest_file_path = os.path.join(config["site_dir"], file)
154166
src_file_path = os.path.join(HERE, file)

mkdocs_git_revision_date_localized_plugin/util.py

Lines changed: 14 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@
88
from babel.dates import format_date, get_timezone
99
from git import Repo, GitCommandError, GitCommandNotFound, InvalidGitRepositoryError, NoSuchPathError
1010

11+
from typing import Any, Dict
12+
1113
logger = logging.getLogger("mkdocs.plugins")
1214

1315

@@ -33,17 +35,17 @@ def _get_repo(self, path: str):
3335
@staticmethod
3436
def _date_formats(
3537
unix_timestamp: float, locale: str = "en", time_zone: str = "UTC"
36-
) -> dict:
38+
) -> Dict[str, Any]:
3739
"""
3840
Returns different date formats / types.
3941
4042
Args:
41-
unix_timestamp (float): a timestamp in seconds since 1970
43+
unix_timestamp (float): A timestamp in seconds since 1970.
4244
locale (str): Locale code of language to use. Defaults to 'en'.
43-
time_zone (str): timezone database name (https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)
45+
time_zone (str): Timezone database name (https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
4446
4547
Returns:
46-
dict: different date formats
48+
dict: Different date formats.
4749
"""
4850
utc_revision_date = datetime.utcfromtimestamp(int(unix_timestamp))
4951
loc_revision_date = utc_revision_date.replace(
@@ -52,9 +54,10 @@ def _date_formats(
5254

5355
return {
5456
"date": format_date(loc_revision_date, format="long", locale=locale),
55-
"datetime": format_date(loc_revision_date, format="long", locale=locale)
56-
+ " "
57-
+ loc_revision_date.strftime("%H:%M:%S"),
57+
"datetime": " ".join([
58+
format_date(loc_revision_date, format="long", locale=locale),
59+
loc_revision_date.strftime("%H:%M:%S"),
60+
]),
5861
"iso_date": loc_revision_date.strftime("%Y-%m-%d"),
5962
"iso_datetime": loc_revision_date.strftime("%Y-%m-%d %H:%M:%S"),
6063
"timeago": '<span class="timeago" datetime="%s" locale="%s"></span>'
@@ -67,17 +70,17 @@ def get_revision_date_for_file(
6770
locale: str = "en",
6871
time_zone: str = "UTC",
6972
fallback_to_build_date: bool = False,
70-
) -> dict:
73+
) -> Dict[str, str]:
7174
"""
7275
Determine localized date variants for a given file
7376
7477
Args:
75-
path (str): Location of a markdownfile that is part of a GIT repository
78+
path (str): Location of a markdown file that is part of a Git repository.
7679
locale (str, optional): Locale code of language to use. Defaults to 'en'.
77-
timezone (str): timezone database name (https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)
80+
timezone (str): Timezone database name (https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
7881
7982
Returns:
80-
dict: localized date variants
83+
dict: Localized date variants.
8184
"""
8285

8386
unix_timestamp = None

requirements.txt

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
mkdocs>=1.0
2+
GitPython
3+
babel>=2.7.0

setup.py

Lines changed: 11 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,20 @@
11
from setuptools import find_packages, setup
22

3-
with open("README.md", "r") as fh:
4-
long_description = fh.read()
3+
file = open("README.md", "r")
4+
LONG_DESCRIPTION = file.read()
5+
file.close()
6+
7+
file = open("requirements.txt", "r")
8+
DEPENDENCIES = file.readlines()
9+
file.close()
10+
11+
del file
512

613
setup(
714
name="mkdocs-git-revision-date-localized-plugin",
815
version="0.7.4",
916
description="Mkdocs plugin that enables displaying the localized date of the last git modification of a markdown file.",
10-
long_description=long_description,
17+
long_description=LONG_DESCRIPTION,
1118
long_description_content_type="text/markdown",
1219
keywords="mkdocs git date timeago babel plugin",
1320
url="https://github.com/timvink/mkdocs-git-revision-date-localized-plugin",
@@ -21,7 +28,7 @@
2128
"License :: OSI Approved :: MIT License",
2229
"Operating System :: OS Independent",
2330
],
24-
install_requires=["mkdocs>=1.0", "GitPython", "babel>=2.7.0"],
31+
install_requires=DEPENDENCIES,
2532
packages=find_packages(),
2633
entry_points={
2734
"mkdocs.plugins": [

tests/test_builds.py

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
"""
2-
Tests running builds on different fresh mkdocs projects
2+
Tests running builds on different fresh mkdocs projects.
33
44
Note that pytest offers a `tmp_path` fixture that we use here.
55
You can reproduce locally with:
@@ -196,8 +196,8 @@ def validate_build(testproject_path, plugin_config: dict = {}):
196196
repo = Util(str(testproject_path / "docs"))
197197
date_formats = repo.get_revision_date_for_file(
198198
path=str(testproject_path / "docs/page_with_tag.md"),
199-
locale=plugin_config.get("locale"),
200-
fallback_to_build_date=plugin_config.get("fallback_to_build_date"),
199+
locale=plugin_config.get("locale"), # type: ignore
200+
fallback_to_build_date=plugin_config.get("fallback_to_build_date"), # type: ignore
201201
)
202202

203203
searches = [x in contents for x in date_formats.values()]
@@ -360,7 +360,7 @@ def test_build_with_timezone(tmp_path):
360360

361361
def test_git_in_docs_dir(tmp_path):
362362
"""
363-
In https://github.com/timvink/mkdocs-git-revision-date-localized-plugin/pull/31
363+
In https://github.com/timvink/mkdocs-git-revision-date-localized-plugin/pull/31
364364
a use case is described where `.git` dir lives in `docs/`
365365
"""
366366

@@ -434,10 +434,10 @@ def test_low_fetch_depth(tmp_path, caplog):
434434
os.environ["GITLAB_CI"] = "1"
435435
result = build_docs_setup(cloned_folder)
436436
assert result.exit_code == 0
437-
assert "Running on a gitlab runner" in caplog.text
437+
assert "Running on a GitLab runner" in caplog.text
438438

439439
del os.environ["GITLAB_CI"]
440440
os.environ["GITHUB_ACTIONS"] = "1"
441441
result = build_docs_setup(cloned_folder)
442442
assert result.exit_code == 0
443-
assert "Running on github actions might" in caplog.text
443+
assert "Running on GitHub Actions might" in caplog.text

tests/test_requirements.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,4 @@ pytest
22
pytest-cov
33
codecov
44
click
5-
mkdocs-material
5+
mkdocs-material

0 commit comments

Comments
 (0)