mkdocs-document-dates 3.1.6__tar.gz → 3.2.1__tar.gz

mkdocs_document_dates-3.2.1/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Aaron Wang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+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:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

{mkdocs_document_dates-3.1.6/mkdocs_document_dates.egg-info → mkdocs_document_dates-3.2.1}/PKG-INFO

@@ -1,13 +1,12 @@
 Metadata-Version: 2.4
 Name: mkdocs-document-dates
-Version: 3.1.6
-Summary: An easy-to-use, lightweight MkDocs plugin for displaying the exact creation time, last modification time and author info of markdown documents.
+Version: 3.2.1
+Summary: A new generation MkDocs plugin for displaying exact meta-info of documents, such as creation time, last update time, authors, email, etc.
 Home-page: https://github.com/jaywhj/mkdocs-document-dates
 Author: Aaron Wang
 Author-email: aaronwqt@gmail.com
 License: MIT
 Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Requires-Python: >=3.7
 Description-Content-Type: text/markdown
@@ -31,7 +30,7 @@ English | [简体中文](README_zh.md)
 
 
 
-An easy-to-use, lightweight MkDocs plugin for displaying the <mark>exact</mark> creation time, last modification time and author info of markdown documents.
+A new generation MkDocs plugin for displaying exact meta-info of documents, such as **creation time, last update time, authors, email**, etc.
 
 ## Features
 
@@ -44,6 +43,7 @@ An easy-to-use, lightweight MkDocs plugin for displaying the <mark>exact</mark>
   - Intelligent repositioning to always float optimally in view
   - Supports automatic theme switching following Material's light/dark color scheme
 - Multi-language support, cross-platform support (Windows, macOS, Linux)
+- Ultimate build efficiency O(1), typically less than 0.2 seconds, regardless of whether the number of documents is 1,000 or 10,000
 
 ## Showcases
 
@@ -76,7 +76,7 @@ plugins:
       time_format: '%H:%M:%S'  # Time format strings (valid only if type=datetime)
       exclude:                 # List of excluded files
         - temp.md              # Exclude specific file
-        - private/*            # Exclude all files in private directory, including subdirectories
+        - private/*            # Exclude all files in private folder, including subfolders
       show_author: true        # Show author or not, default: true
 ```
 
@@ -84,7 +84,7 @@ plugins:
 
 The plugin will automatically get the exact time of the document, will automatically cache the creation time, but of course, you can also specify it manually in `Front Matter`
 
-Priority order: `Front Matter` > `Cache Files` > `File System Timestamps`
+Priority order: `Front Matter` > `File System Timestamps(Cached)` > `Git Timestamps`
 
 ```yaml
 ---
@@ -102,7 +102,7 @@ modified: 2025-02-23
 
 The plugin will automatically get the author of the document, will parse the email and make a link, also you can specify it manually in `Front Matter`
 
-Priority order: `Front Matter` > `Git Author` > `site_author (mkdocs.yml)` > `PC Username`
+Priority order: `Front Matter` > `Git Author` > `site_author(mkdocs.yml)` > `PC Username`
 
 ```yaml
 ---
@@ -118,9 +118,9 @@ email: e-name@gmail.com
 
 ## Customization
 
-The plugin supports deep customization, such as **icon style, font style, theme color, animation type, dividing line**, etc. Everything is customizable (I've already written the code, you just need to turn on the uncomment switch):
+The plugin supports deep customization, such as **icon style, theme color, font, animation, dividing line**, etc. Everything is customizable (Find the file below and turn on the uncomment switch):
 
-|        Function：        | Location：                               |
+|        Category:        | Location:                               |
 | :----------------------: | ---------------------------------------- |
 |     **Style & Theme**     | `docs/assets/document_dates/user.config.css` |
 | **Properties & Functions** | `docs/assets/document_dates/user.config.js` |
@@ -129,7 +129,7 @@ The plugin supports deep customization, such as **icon style, font style, theme
 **Tip**: when `type: timeago` is set, timeago.js is enabled to render dynamic time, `timeago.min.js` only contains English and Chinese by default, if you need to load other languages, you can configure it as below (choose one):
 
 - In `user.config.js`, refer to [the demo commented out](https://github.com/jaywhj/mkdocs-document-dates/blob/main/mkdocs_document_dates/static/config/user.config.js) at the bottom, translate it into your local language
-- In `mkdocs.yml`, add the following two lines to configure the full version of `timeago.full.min.js` to load all languages at once
+- In `mkdocs.yml`, configure the full version of `timeago.full.min.js` to load all languages at once
     ```yaml
     extra_javascript:
       - assets/document_dates/core/timeago.full.min.js
@@ -147,7 +147,7 @@ The plugin supports deep customization, such as **icon style, font style, theme
 ![06-change-theme](mkdocs_document_dates/demo_images/06-change-theme.png)
 ![08-pop-up-from-bottom](mkdocs_document_dates/demo_images/08-pop-up-from-bottom.png)
 
-## Used in templates
+## Template Variables
 
 You can access the meta-info of a document in a template using the following variables:
 

{mkdocs_document_dates-3.1.6 → mkdocs_document_dates-3.2.1}/README.md

@@ -4,7 +4,7 @@ English | [简体中文](README_zh.md)
 
 
 
-An easy-to-use, lightweight MkDocs plugin for displaying the <mark>exact</mark> creation time, last modification time and author info of markdown documents.
+A new generation MkDocs plugin for displaying exact meta-info of documents, such as **creation time, last update time, authors, email**, etc.
 
 ## Features
 
@@ -17,6 +17,7 @@ An easy-to-use, lightweight MkDocs plugin for displaying the <mark>exact</mark>
   - Intelligent repositioning to always float optimally in view
   - Supports automatic theme switching following Material's light/dark color scheme
 - Multi-language support, cross-platform support (Windows, macOS, Linux)
+- Ultimate build efficiency O(1), typically less than 0.2 seconds, regardless of whether the number of documents is 1,000 or 10,000
 
 ## Showcases
 
@@ -49,7 +50,7 @@ plugins:
       time_format: '%H:%M:%S'  # Time format strings (valid only if type=datetime)
       exclude:                 # List of excluded files
         - temp.md              # Exclude specific file
-        - private/*            # Exclude all files in private directory, including subdirectories
+        - private/*            # Exclude all files in private folder, including subfolders
       show_author: true        # Show author or not, default: true
 ```
 
@@ -57,7 +58,7 @@ plugins:
 
 The plugin will automatically get the exact time of the document, will automatically cache the creation time, but of course, you can also specify it manually in `Front Matter`
 
-Priority order: `Front Matter` > `Cache Files` > `File System Timestamps`
+Priority order: `Front Matter` > `File System Timestamps(Cached)` > `Git Timestamps`
 
 ```yaml
 ---
@@ -75,7 +76,7 @@ modified: 2025-02-23
 
 The plugin will automatically get the author of the document, will parse the email and make a link, also you can specify it manually in `Front Matter`
 
-Priority order: `Front Matter` > `Git Author` > `site_author (mkdocs.yml)` > `PC Username`
+Priority order: `Front Matter` > `Git Author` > `site_author(mkdocs.yml)` > `PC Username`
 
 ```yaml
 ---
@@ -91,9 +92,9 @@ email: e-name@gmail.com
 
 ## Customization
 
-The plugin supports deep customization, such as **icon style, font style, theme color, animation type, dividing line**, etc. Everything is customizable (I've already written the code, you just need to turn on the uncomment switch):
+The plugin supports deep customization, such as **icon style, theme color, font, animation, dividing line**, etc. Everything is customizable (Find the file below and turn on the uncomment switch):
 
-|        Function：        | Location：                               |
+|        Category:        | Location:                               |
 | :----------------------: | ---------------------------------------- |
 |     **Style & Theme**     | `docs/assets/document_dates/user.config.css` |
 | **Properties & Functions** | `docs/assets/document_dates/user.config.js` |
@@ -102,7 +103,7 @@ The plugin supports deep customization, such as **icon style, font style, theme
 **Tip**: when `type: timeago` is set, timeago.js is enabled to render dynamic time, `timeago.min.js` only contains English and Chinese by default, if you need to load other languages, you can configure it as below (choose one):
 
 - In `user.config.js`, refer to [the demo commented out](https://github.com/jaywhj/mkdocs-document-dates/blob/main/mkdocs_document_dates/static/config/user.config.js) at the bottom, translate it into your local language
-- In `mkdocs.yml`, add the following two lines to configure the full version of `timeago.full.min.js` to load all languages at once
+- In `mkdocs.yml`, configure the full version of `timeago.full.min.js` to load all languages at once
     ```yaml
     extra_javascript:
       - assets/document_dates/core/timeago.full.min.js
@@ -120,7 +121,7 @@ The plugin supports deep customization, such as **icon style, font style, theme
 ![06-change-theme](mkdocs_document_dates/demo_images/06-change-theme.png)
 ![08-pop-up-from-bottom](mkdocs_document_dates/demo_images/08-pop-up-from-bottom.png)
 
-## Used in templates
+## Template Variables
 
 You can access the meta-info of a document in a template using the following variables:
 

mkdocs_document_dates-3.2.1/mkdocs_document_dates/cache_manager.py

@@ -0,0 +1,122 @@
+import logging
+import subprocess
+from pathlib import Path
+from .utils import read_json_cache, read_jsonl_cache, write_jsonl_cache, get_file_creation_time
+
+logger = logging.getLogger("mkdocs.plugins.document_dates")
+logger.setLevel(logging.WARNING)  # DEBUG, INFO, WARNING, ERROR, CRITICAL
+
+def find_mkdocs_projects():
+    projects = []
+    try:
+        git_root = Path(subprocess.check_output(
+            ['git', 'rev-parse', '--show-toplevel'],
+            text=True, encoding='utf-8'
+        ).strip())
+
+        # 遍历 git_root 及子目录, 寻找 mkdocs.yml 文件
+        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)
+
+        if not projects:
+            logger.warning("No MkDocs projects found in the repository")
+    except subprocess.CalledProcessError as e:
+        logger.error(f"Failed to find the Git repository root: {e}")
+    except Exception as e:
+        logger.error(f"Unexpected error while searching for MkDocs projects: {e}")
+    
+    return projects
+
+def setup_gitattributes(docs_dir: Path):
+    try:
+        gitattributes_path = docs_dir / '.gitattributes'
+        union_merge_line = ".dates_cache.jsonl merge=union"
+        # custom_merge_line = ".dates_cache.json merge=custom_json_merge"
+        content = gitattributes_path.read_text(encoding='utf-8') if gitattributes_path.exists() else ""
+        if union_merge_line not in content:
+            if content and not content.endswith('\n'):
+                content += '\n'
+            content += f"{union_merge_line}\n"
+            gitattributes_path.write_text(content, encoding='utf-8')
+            subprocess.run(["git", "add", str(gitattributes_path)], check=True)
+            logger.info(f"Updated .gitattributes file: {gitattributes_path}")
+            return True
+    except (IOError, OSError) as e:
+        logger.error(f"Failed to read/write .gitattributes file: {e}")
+    except Exception as e:
+        logger.error(f"Failed to add .gitattributes to git: {e}")
+    return False
+
+def update_cache():
+    global_updated = False
+
+    for project_dir in find_mkdocs_projects():
+        try:
+            project_updated = False
+
+            docs_dir = project_dir / 'docs'
+            if not docs_dir.exists():
+                logger.warning(f"Document directory does not exist: {docs_dir}")
+                continue
+
+            # 设置.gitattributes文件
+            global_updated = setup_gitattributes(docs_dir)
+
+            # 获取docs目录下已跟踪(tracked)的markdown文件
+            cmd = ["git", "ls-files", "*.md"]
+            result = subprocess.run(cmd, cwd=docs_dir, capture_output=True, text=True)
+            tracked_files = result.stdout.splitlines() if result.stdout else []
+
+            if not tracked_files:
+                logger.info(f"No tracked markdown files found in {docs_dir}")
+                continue
+
+            # 读取旧的JSON缓存文件（如果存在）
+            json_cache_file = docs_dir / '.dates_cache.json'
+            json_dates_cache = read_json_cache(json_cache_file)
+
+            # 读取新的JSONL缓存文件（如果存在）
+            jsonl_cache_file = docs_dir / '.dates_cache.jsonl'
+            jsonl_dates_cache = read_jsonl_cache(jsonl_cache_file)
+
+            # 根据 git已跟踪的文件来更新
+            for rel_path in tracked_files:
+                try:
+                    # 如果文件已在JSONL缓存中，跳过
+                    if rel_path in jsonl_dates_cache:
+                        continue
+
+                    full_path = docs_dir / rel_path
+                    # 处理新文件或迁移旧JSON缓存
+                    if rel_path in json_dates_cache:
+                        jsonl_dates_cache[rel_path] = json_dates_cache[rel_path]
+                        project_updated = True
+                    elif full_path.exists():
+                        created_time = get_file_creation_time(full_path).astimezone()
+                        jsonl_dates_cache[rel_path] = {
+                            "created": created_time.isoformat()
+                        }
+                        project_updated = True
+                except Exception as e:
+                    logger.error(f"Error processing file {rel_path}: {e}")
+                    continue
+
+            # 标记删除不再跟踪的文件
+            if len(jsonl_dates_cache) > len(tracked_files):
+                project_updated = True
+
+            # 如果有更新，写入JSONL缓存文件
+            if project_updated or not jsonl_cache_file.exists():
+                global_updated = write_jsonl_cache(jsonl_cache_file, jsonl_dates_cache, tracked_files)
+        except subprocess.CalledProcessError as e:
+            logger.error(f"Failed to execute git command: {e}")
+            continue
+        except Exception as e:
+            logger.error(f"Error processing project directory {project_dir}: {e}")
+            continue
+    return global_updated
+
+
+if __name__ == "__main__":
+    update_cache()

mkdocs_document_dates-3.2.1/mkdocs_document_dates/hooks_installer.py

@@ -0,0 +1,109 @@
+import os
+import sys
+import logging
+import subprocess
+from pathlib import Path
+import platform
+
+logger = logging.getLogger("mkdocs.plugins.document_dates")
+logger.setLevel(logging.WARNING)  # DEBUG, INFO, WARNING, ERROR, CRITICAL
+
+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 check_python_version(interpreter):
+    try:
+        result = subprocess.run(
+            [interpreter, "-c", "import sys; print(sys.version_info >= (3, 7))"],
+            capture_output=True, text=True)
+        if result.returncode == 0 and result.stdout.strip().lower() == 'true':
+            return True
+        else:
+            logger.warning(f"Low python version, requires python_requires >=3.7")
+    except Exception as e:
+        logger.info(f"Failed to check {interpreter}: {str(e)}")
+    return False
+
+def detect_python_interpreter():
+    # 检查可能的Python解释器
+    python_interpreters = ['python3', 'python']
+    for interpreter in python_interpreters:
+        if check_python_version(interpreter):
+            return f'#!/usr/bin/env {interpreter}'
+    
+    # 如果都失败了，使用当前运行的Python解释器
+    return f'#!{sys.executable}'
+
+def setup_hooks_directory():
+    config_dir = get_config_dir() / 'mkdocs-document-dates' / 'hooks'
+    try:
+        config_dir.mkdir(parents=True, exist_ok=True)
+        os.chmod(config_dir, 0o755)
+        return config_dir
+    except PermissionError:
+        logger.error(f"No permission to create directory: {config_dir}")
+    except Exception as e:
+        logger.error(f"Failed to create directory {config_dir}: {str(e)}")
+    return None
+
+def install_hook_file(source_dir: Path, target_dir: Path):
+    try:
+        shebang = detect_python_interpreter()
+        for item in source_dir.iterdir():
+            # 跳过隐藏文件和目录
+            if item.name.startswith('.') or not item.is_file():
+                continue
+            # 添加 shebang 行
+            content = item.read_text(encoding='utf-8')
+            if content.startswith('#!'):
+                content = shebang + os.linesep + content[content.find('\n')+1:]
+            else:
+                content = shebang + os.linesep + content
+
+            target_hook_path = target_dir / item.name
+            target_hook_path.write_text(content, encoding='utf-8')
+            os.chmod(target_hook_path, 0o755)
+
+        return True
+    except Exception as e:
+        logger.error(f"Failed to create hook file {target_hook_path}: {str(e)}")
+    return False
+
+def configure_git_hooks(hooks_dir):
+    try:
+        # 配置自定义合并驱动
+        # script_path = hooks_dir / 'json_merge_driver.py'
+        # subprocess.run(['git', 'config', '--global', 'merge.custom_json_merge.name', 'Custom JSON merge driver'], check=True)
+        # subprocess.run(['git', 'config', '--global', 'merge.custom_json_merge.driver', f'"{sys.executable}" "{script_path}" %O %A %B'], check=True)
+
+        subprocess.run(['git', 'config', '--global', 'core.hooksPath', str(hooks_dir)], check=True)
+        logger.info(f"Git hooks successfully installed in: {hooks_dir}")
+        return True
+    except Exception:
+        logger.warning("Git not detected, using plugin in a no-Git environment")
+    return False
+
+def install():
+    try:
+        # 创建hooks目录
+        target_dir = setup_hooks_directory()
+        if not target_dir:
+            return False
+
+        # 安装hook文件
+        source_dir = Path(__file__).parent / 'hooks'
+        if not install_hook_file(source_dir, target_dir):
+            return False
+
+        # 配置git hooks路径
+        return configure_git_hooks(target_dir)
+
+    except Exception as e:
+        logger.error(f"Unexpected error during hooks installation: {str(e)}")
+        return False
+
+if __name__ == '__main__':
+    install()