mkdocs-document-dates 2.3.0__tar.gz → 2.3.2__tar.gz

{mkdocs_document_dates-2.3.0 → mkdocs_document_dates-2.3.2}/LICENSE

@@ -9,4 +9,3 @@ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 copies of the Software, and to permit persons to whom the Software is
 furnished to do so, subject to the following conditions:
 
-[... 后续 MIT 许可证内容 ...]

{mkdocs_document_dates-2.3.0 → mkdocs_document_dates-2.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: mkdocs-document-dates
-Version: 2.3.0
+Version: 2.3.2
 Summary: A MkDocs plugin for displaying accurate document creation and last modification dates.
 Home-page: https://github.com/jaywhj/mkdocs-document-dates
 Author: Aaron Wang
@@ -107,18 +107,18 @@ modified: 2025-02-23
 
 ## Notes
 
-- It still works when using CI/CD build systems (e.g. Github Actions)
-  - Used a cache file `.dates_cache.json` to solve this problem
-  - You can configure it like this (line 3) in your .github/workflows/ci.yml:
-    
+- It still works when using CI/CD build systems (e.g. Github Actions), used a cache file `.dates_cache.json` to solve this problem:
+    1. First, you can configure the workflow like this (penultimate line) in your .github/workflows/ci.yml:
     ```
     ...
     
-      - run: pip install mkdocs-document-dates
-      - run: mkdocs gh-deploy --force
+        - run: pip install mkdocs-document-dates
+        - run: mkdocs gh-deploy --force
     ```
-  - Then update your Markdown files in MkDocs as normal, execute commands such as mkdocs build or directly git add, commit, and push
-    - Make sure you have installed python3 ahead of time and set environment variables
+    2. Then update your Markdown document in MkDocs as normal
+    3. After running git add and git commit, you will see the auto-generated cache file .dates_cache.json (hidden by default) in the `docs` folder under MkDocs
+        - Make sure you have installed python3 ahead of time and set environment variables
+    4. Finally, run git push, and you can see that there are also .dates_cache.json files in the docs directory in the GitHub repository, which means success
 - Priority of time reads:
-  - `Front Matter` > `Cache file` > `Filesystem timestamp`
+    - `Front Matter` > `Cache file` > `Filesystem timestamp`
 - If you are using MkDocs on a Linux system, the modification time is used as the creation time because of system limitations. If you need the exact creation time, you can specify it manually in Front Matter

{mkdocs_document_dates-2.3.0 → mkdocs_document_dates-2.3.2}/README.md

@@ -85,18 +85,18 @@ modified: 2025-02-23
 
 ## Notes
 
-- It still works when using CI/CD build systems (e.g. Github Actions)
-  - Used a cache file `.dates_cache.json` to solve this problem
-  - You can configure it like this (line 3) in your .github/workflows/ci.yml:
-    
+- It still works when using CI/CD build systems (e.g. Github Actions), used a cache file `.dates_cache.json` to solve this problem:
+    1. First, you can configure the workflow like this (penultimate line) in your .github/workflows/ci.yml:
     ```
     ...
     
-      - run: pip install mkdocs-document-dates
-      - run: mkdocs gh-deploy --force
+        - run: pip install mkdocs-document-dates
+        - run: mkdocs gh-deploy --force
     ```
-  - Then update your Markdown files in MkDocs as normal, execute commands such as mkdocs build or directly git add, commit, and push
-    - Make sure you have installed python3 ahead of time and set environment variables
+    2. Then update your Markdown document in MkDocs as normal
+    3. After running git add and git commit, you will see the auto-generated cache file .dates_cache.json (hidden by default) in the `docs` folder under MkDocs
+        - Make sure you have installed python3 ahead of time and set environment variables
+    4. Finally, run git push, and you can see that there are also .dates_cache.json files in the docs directory in the GitHub repository, which means success
 - Priority of time reads:
-  - `Front Matter` > `Cache file` > `Filesystem timestamp`
+    - `Front Matter` > `Cache file` > `Filesystem timestamp`
 - If you are using MkDocs on a Linux system, the modification time is used as the creation time because of system limitations. If you need the exact creation time, you can specify it manually in Front Matter

mkdocs_document_dates-2.3.2/mkdocs_document_dates/__init__.py

@@ -0,0 +1,13 @@
+"""MkDocs Document Dates Plugin."""
+
+__version__ = '2.3.1'
+
+from .hooks_installer import install
+
+# 在包被导入时自动执行 hooks 安装
+try:
+    result = install()
+    if not result:
+        print("Tip: Git hooks installation was skipped (probably because Git was not detected or not in the Git repository)")
+except Exception as e:
+    print(f"Warning: Git hooks installation failed: {e}")

{mkdocs_document_dates-2.3.0 → mkdocs_document_dates-2.3.2}/mkdocs_document_dates/hooks/pre-commit

@@ -9,25 +9,23 @@ from datetime import datetime
 from pathlib import Path
 
 def find_mkdocs_projects():
-    """查找当前 git 仓库中的所有 MkDocs 项目"""
     try:
         git_root = Path(subprocess.check_output(
             ['git', 'rev-parse', '--show-toplevel'],
             text=True, encoding='utf-8'
         ).strip())
-        
+
         projects = []
         for config_file in git_root.rglob('mkdocs.y*ml'):
             if config_file.name.lower() in ('mkdocs.yml', 'mkdocs.yaml'):
                 projects.append(config_file.parent)
-        
+
         return projects
     except subprocess.CalledProcessError as e:
-        print(f"查找 Git 仓库根目录失败: {e}", file=sys.stderr)
+        print(f"Failed to find the Git repository root: {e}", file=sys.stderr)
         return []
 
 def get_file_dates(file_path):
-    """获取文件的创建和修改时间"""
     try:
         stat = os.stat(file_path)
         modified = datetime.fromtimestamp(stat.st_mtime)
@@ -49,11 +47,10 @@ def get_file_dates(file_path):
         return current_time.isoformat(), current_time.isoformat()
 
 def update_dates_cache():
-    """更新文档时间缓存"""
     for project_dir in find_mkdocs_projects():
         docs_dir = project_dir / 'docs'
         if not docs_dir.exists():
-            print(f"文档目录不存在: {docs_dir}")
+            print(f"Document directory does not exist: {docs_dir}")
             continue
 
         dates_cache = {}
@@ -68,7 +65,7 @@ def update_dates_cache():
                     "modified": modified
                 }
             except Exception as e:
-                print(f"处理文件 {md_file} 时出错: {e}")
+                print(f"Error processing file {md_file}: {e}")
 
         if not dates_cache:
             continue
@@ -78,14 +75,14 @@ def update_dates_cache():
             with open(cache_file, "w") as f:
                 json.dump(dates_cache, f, indent=2, ensure_ascii=False)
             subprocess.run(["git", "add", str(cache_file)], check=True)
-            # print(f"缓存文件 {cache_file} 已更新.")
+            # print(f"The cache file {cache_file} has been updated")
         except Exception as e:
-            print(f"写入缓存文件时出错: {e}", file=sys.stderr)
+            print(f"Error writing to cache file: {e}", file=sys.stderr)
             raise
 
 if __name__ == "__main__":
     try:
         update_dates_cache()
     except Exception as e:
-        print(f"Hook 执行出错: {e}", file=sys.stderr)
+        print(f"Hook execution error: {e}", file=sys.stderr)
         sys.exit(1)

{mkdocs_document_dates-2.3.0 → mkdocs_document_dates-2.3.2}/mkdocs_document_dates/hooks_installer.py

@@ -6,20 +6,18 @@ from pathlib import Path
 import platform
 
 def get_config_dir():
-    """获取用户配置目录"""
     if platform.system().lower().startswith('win'):
         return Path(os.getenv('APPDATA', str(Path.home() / 'AppData' / 'Roaming')))
     else:
         return Path.home() / '.config'
 
 def install():
-    """安装 git hooks"""
     try:
         # 检查 git 是否可用
         try:
             subprocess.run(['git', '--version'], check=True, capture_output=True, encoding='utf-8')
         except (subprocess.CalledProcessError, FileNotFoundError):
-            print("提示: 未检测到 Git, 跳过 hooks 安装")
+            print("Tip: Git not detected, skip hooks installation")
             return False
         
         # 准备配置目录
@@ -27,10 +25,10 @@ def install():
         try:
             config_dir.mkdir(parents=True, exist_ok=True)
         except PermissionError:
-            print(f"错误: 无权限创建目录: {config_dir}")
+            print(f"Error: No permission to create directory: {config_dir}")
             return False
         except Exception as e:
-            print(f"错误: 创建目录失败: {config_dir}, 原因: {e}")
+            print(f"Error: Failed to create directory: {config_dir}, reason: {e}")
             return False
 
         hook_path = config_dir / 'pre-commit'
@@ -38,16 +36,16 @@ def install():
         # 复制 hook 文件到配置目录
         source_hook = Path(__file__).parent / 'hooks' / 'pre-commit'
         if not source_hook.exists():
-            print(f"错误: 源 hook 文件不存在: {source_hook}")
+            print(f"Error: Source hook file does not exist: {source_hook}")
             return False
 
         try:
             shutil.copy2(source_hook, hook_path)
         except PermissionError:
-            print(f"错误: 无权限复制文件到: {hook_path}")
+            print(f"Error: No permission to copy file to: {hook_path}")
             return False
         except Exception as e:
-            print(f"错误: 复制文件失败, 原因: {e}")
+            print(f"Error: Failed to copy file, reason: {e}")
             return False
 
         # 设置文件权限
@@ -55,20 +53,20 @@ def install():
             os.chmod(config_dir, 0o755)
             os.chmod(hook_path, 0o755)
         except OSError as e:
-            print(f"警告: 设置权限时出错: {e}")
+            print(f"Warning: Error setting permissions: {e}")
 
         # 配置全局 git hooks 路径
         try:
             subprocess.run(['git', 'config', '--global', 'core.hooksPath', 
                           str(config_dir)], check=True, encoding='utf-8')
-            print(f"Git hooks 已安装到: {config_dir}")
+            # print(f"Git hooks are installed in the: {config_dir}")
             return True
         except subprocess.CalledProcessError as e:
-            print(f"错误: 设置 git hooks 路径失败: {e}")
+            print(f"Error: Setting git hooks path failed: {e}")
             return False
             
     except Exception as e:
-        print(f"安装 hooks 时出错: {e}")
+        print(f"Error installing hooks: {e}")
         return False
 
 if __name__ == '__main__':

{mkdocs_document_dates-2.3.0 → mkdocs_document_dates-2.3.2}/mkdocs_document_dates/lang/__init__.py

@@ -2,7 +2,6 @@ from pathlib import Path
 import importlib.util
 
 def load_translations():
-    """加载所有可用的翻译"""
     translations = {}
     translations_dir = Path(__file__).parent
     

{mkdocs_document_dates-2.3.0 → mkdocs_document_dates-2.3.2}/mkdocs_document_dates/lang/ar.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 translations = {
     'just_now': 'الآن',
     'seconds_ago': 'منذ {} ثانية',

{mkdocs_document_dates-2.3.0 → mkdocs_document_dates-2.3.2}/mkdocs_document_dates/lang/de.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 translations = {
     'just_now': 'gerade jetzt',
     'seconds_ago': 'vor {} Sekunden',

{mkdocs_document_dates-2.3.0 → mkdocs_document_dates-2.3.2}/mkdocs_document_dates/lang/en.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 translations = {
     'just_now': 'just now',
     'seconds_ago': '{} seconds ago',

{mkdocs_document_dates-2.3.0 → mkdocs_document_dates-2.3.2}/mkdocs_document_dates/lang/es.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 translations = {
     'just_now': 'justo ahora',
     'seconds_ago': 'hace {} segundos',

{mkdocs_document_dates-2.3.0 → mkdocs_document_dates-2.3.2}/mkdocs_document_dates/lang/fr.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 translations = {
     'just_now': 'à l\'instant',
     'seconds_ago': 'il y a {} secondes',

{mkdocs_document_dates-2.3.0 → mkdocs_document_dates-2.3.2}/mkdocs_document_dates/lang/ja.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 translations = {
     'just_now': 'たった今',
     'seconds_ago': '{} 秒前',

{mkdocs_document_dates-2.3.0 → mkdocs_document_dates-2.3.2}/mkdocs_document_dates/lang/ko.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 translations = {
     'just_now': '방금',
     'seconds_ago': '{} 초 전',

{mkdocs_document_dates-2.3.0 → mkdocs_document_dates-2.3.2}/mkdocs_document_dates/lang/ru.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 translations = {
     'just_now': 'только что',
     'seconds_ago': '{} секунд назад',

{mkdocs_document_dates-2.3.0 → mkdocs_document_dates-2.3.2}/mkdocs_document_dates/lang/zh.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 translations = {
     'just_now': '刚刚',
     'seconds_ago': '{} 秒前',

{mkdocs_document_dates-2.3.0 → mkdocs_document_dates-2.3.2}/mkdocs_document_dates/lang/zh_tw.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 translations = {
     'just_now': '剛剛',
     'seconds_ago': '{} 秒前',

{mkdocs_document_dates-2.3.0 → mkdocs_document_dates-2.3.2}/mkdocs_document_dates/plugin.py

@@ -23,11 +23,9 @@ class DocumentDatesPlugin(BasePlugin):
         self.translations = load_translations()
 
     def _get_css_content(self):
-        """返回插件的 CSS 样式"""
         return DOCUMENT_DATES_CSS
 
     def on_config(self, config):
-        """配置插件并添加必要的 CSS"""
         if 'extra_css' not in config:
             config['extra_css'] = []
         
@@ -45,8 +43,6 @@ class DocumentDatesPlugin(BasePlugin):
         return config
 
     def _get_date_info(self, created, modified):
-        """格式化日期信息的 HTML"""
-        # 获取翻译字典
         locale = self.config['locale']
         if locale not in self.translations:
             locale = 'en'
@@ -55,16 +51,15 @@ class DocumentDatesPlugin(BasePlugin):
         return (
             f"<div class='document-dates-plugin-wrapper'>"
             f"<div class='document-dates-plugin'>"
-            f"<span title='{t['created_time']}'><span class='material-icons'>add_circle</span>"
+            f"<span title='{t['created_time']}: {created.strftime(self.config['date_format'])}'><span class='material-icons'>add_circle</span>"
             f"{self._get_formatted_date(created)}</span>"
-            f"<span title='{t['modified_time']}'><span class='material-icons'>update</span>"
+            f"<span title='{t['modified_time']}: {modified.strftime(self.config['date_format'])}'><span class='material-icons'>update</span>"
             f"{self._get_formatted_date(modified)}</span>"
             f"</div>"
             f"</div>"
         )
 
     def _insert_date_info(self, markdown, date_info):
-        """根据配置将日期信息插入到合适的位置"""
         if not markdown.strip():
             return markdown
             
@@ -78,7 +73,6 @@ class DocumentDatesPlugin(BasePlugin):
         return f"{markdown}\n\n{date_info}"
 
     def on_page_markdown(self, markdown, page, config, files):
-        """处理页面内容，添加日期信息"""
         file_path = Path(page.file.abs_src_path)
         
         if self._is_excluded(file_path, Path(config['docs_dir'])):
@@ -97,19 +91,12 @@ class DocumentDatesPlugin(BasePlugin):
         return self._insert_date_info(markdown, date_info)
 
     def _is_excluded(self, file_path: Path, docs_dir: Path) -> bool:
-        """检查文件是否在排除列表中"""
         for pattern in self.config['exclude']:
             if self._matches_exclude_pattern(file_path, docs_dir, pattern):
                 return True
         return False
 
     def _matches_exclude_pattern(self, file_path: Path, docs_dir: Path, pattern: str) -> bool:
-        """检查文件是否匹配排除模式
-        支持三种匹配模式：
-        1. 具体文件路径：支持多级目录，如 'private/temp.md'
-        2. 目录下所有文件：使用 '*' 通配符，如 'private/*'，匹配包含子目录的所有文件
-        3. 指定目录下特定类型文件：如 'private/*.md'，仅匹配当前目录下的特定类型文件
-        """
         try:
             # 获取相对于 docs_dir 的路径
             rel_path = file_path.relative_to(docs_dir)
@@ -136,13 +123,11 @@ class DocumentDatesPlugin(BasePlugin):
             return False
 
     def _process_meta_dates(self, meta: dict, created: datetime, modified: datetime) -> tuple[datetime, datetime]:
-        """处理 frontmatter 中的日期"""
         result_created = self._parse_meta_date(meta.get('created'), created)
         result_modified = self._parse_meta_date(meta.get('modified'), modified)
         return result_created, result_modified
 
     def _parse_meta_date(self, date_str: str | None, default_date: datetime) -> datetime:
-        """解析 meta 中的日期字符串"""
         if not date_str:
             return default_date
 
@@ -152,7 +137,6 @@ class DocumentDatesPlugin(BasePlugin):
             return default_date
 
     def _get_file_dates(self, file_path, config):
-        """获取文件的创建时间和修改时间"""
         try:
             docs_dir = Path(config['docs_dir'])
             rel_path = str(Path(file_path).relative_to(docs_dir))
@@ -180,7 +164,7 @@ class DocumentDatesPlugin(BasePlugin):
                     created = datetime.fromtimestamp(stat.st_birthtime)
                 except AttributeError:
                     created = datetime.fromtimestamp(stat.st_ctime)
-            else:  # Linux 和其他系统
+            else:  # Linux
                 created = modified
 
             return created, modified
@@ -190,7 +174,6 @@ class DocumentDatesPlugin(BasePlugin):
             return current_time, current_time
 
     def _get_timeago(self, date):
-        """将日期格式化为 timeago 格式"""
         now = datetime.now()
         diff = now - date
         seconds = diff.total_seconds()
@@ -232,7 +215,6 @@ class DocumentDatesPlugin(BasePlugin):
             return t['years_ago'].format(int(seconds / 31536000))
 
     def _get_formatted_date(self, date):
-        """格式化日期，支持 timeago、date 和 datetime 格式"""
         if self.config['type'] == 'timeago':
             return self._get_timeago(date)
         elif self.config['type'] == 'datetime':

{mkdocs_document_dates-2.3.0 → mkdocs_document_dates-2.3.2}/mkdocs_document_dates/styles.py

@@ -1,4 +1,3 @@
-"""CSS 样式定义"""
 
 DOCUMENT_DATES_CSS = """
 .document-dates-plugin {

{mkdocs_document_dates-2.3.0 → mkdocs_document_dates-2.3.2}/mkdocs_document_dates.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: mkdocs-document-dates
-Version: 2.3.0
+Version: 2.3.2
 Summary: A MkDocs plugin for displaying accurate document creation and last modification dates.
 Home-page: https://github.com/jaywhj/mkdocs-document-dates
 Author: Aaron Wang
@@ -107,18 +107,18 @@ modified: 2025-02-23
 
 ## Notes
 
-- It still works when using CI/CD build systems (e.g. Github Actions)
-  - Used a cache file `.dates_cache.json` to solve this problem
-  - You can configure it like this (line 3) in your .github/workflows/ci.yml:
-    
+- It still works when using CI/CD build systems (e.g. Github Actions), used a cache file `.dates_cache.json` to solve this problem:
+    1. First, you can configure the workflow like this (penultimate line) in your .github/workflows/ci.yml:
     ```
     ...
     
-      - run: pip install mkdocs-document-dates
-      - run: mkdocs gh-deploy --force
+        - run: pip install mkdocs-document-dates
+        - run: mkdocs gh-deploy --force
     ```
-  - Then update your Markdown files in MkDocs as normal, execute commands such as mkdocs build or directly git add, commit, and push
-    - Make sure you have installed python3 ahead of time and set environment variables
+    2. Then update your Markdown document in MkDocs as normal
+    3. After running git add and git commit, you will see the auto-generated cache file .dates_cache.json (hidden by default) in the `docs` folder under MkDocs
+        - Make sure you have installed python3 ahead of time and set environment variables
+    4. Finally, run git push, and you can see that there are also .dates_cache.json files in the docs directory in the GitHub repository, which means success
 - Priority of time reads:
-  - `Front Matter` > `Cache file` > `Filesystem timestamp`
+    - `Front Matter` > `Cache file` > `Filesystem timestamp`
 - If you are using MkDocs on a Linux system, the modification time is used as the creation time because of system limitations. If you need the exact creation time, you can specify it manually in Front Matter

{mkdocs_document_dates-2.3.0 → mkdocs_document_dates-2.3.2}/setup.py

@@ -7,7 +7,7 @@ try:
 except FileNotFoundError:
     long_description = "A MkDocs plugin for displaying accurate document creation and last modification dates."
 
-VERSION = '2.3.0'
+VERSION = '2.3.2'
 
 setup(
     name="mkdocs-document-dates",

mkdocs_document_dates-2.3.0/mkdocs_document_dates/__init__.py

@@ -1,13 +0,0 @@
-"""MkDocs Document Dates Plugin."""
-
-__version__ = '2.3.0'
-
-from .hooks_installer import install
-
-# 在包被导入时自动执行 hooks 安装
-try:
-    result = install()
-    if not result:
-        print("提示: Git hooks 安装被跳过（可能是因为未检测到 Git 或不在 Git 仓库中）")
-except Exception as e:
-    print(f"警告: Git hooks 安装失败: {e}")