mkdocs-document-dates 3.1.1__tar.gz → 3.1.3__tar.gz

{mkdocs_document_dates-3.1.1 → mkdocs_document_dates-3.1.3}/PKG-INFO

@@ -1,9 +1,11 @@
 Metadata-Version: 2.4
 Name: mkdocs-document-dates
-Version: 3.1.1
+Version: 3.1.3
 Summary: An easy-to-use, lightweight MkDocs plugin for displaying the exact creation time, last modification time and author info of markdown documents.
 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
@@ -12,10 +14,12 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: mkdocs>=1.0.0
 Dynamic: author
+Dynamic: author-email
 Dynamic: classifier
 Dynamic: description
 Dynamic: description-content-type
 Dynamic: home-page
+Dynamic: license
 Dynamic: license-file
 Dynamic: requires-dist
 Dynamic: requires-python
@@ -70,15 +74,15 @@ plugins:
   - document-dates:
       position: top            # Display position: top (after title)  bottom (end of document), default: bottom
       type: date               # Date type: date  datetime  timeago, default: date
-      locale: en               # Localization: zh zh_tw en es fr de ar ja ko ru, default: en
-      date_format: '%Y-%m-%d'  # Date format, Supports all Python datetime format strings, e.g., %Y-%m-%d, %b %d, %Y, etc
+      locale: en               # Localization: zh zh_TW en es fr de ar ja ko ru, default: en
+      date_format: '%Y-%m-%d'  # Date format, supports all python datetime format strings, e.g., %Y-%m-%d, %b %d, %Y, etc
       time_format: '%H:%M:%S'  # Time format (valid only if type=datetime)
       exclude:                 # List of excluded files
         - temp.md              # Exclude specific file
         - private/*            # Exclude all files in private directory, including subdirectories
         - drafts/*.md          # Exclude all markdown files in the current directory drafts, but not subdirectories
       
-      show_author: true        # Whether to display author: true false, default: true
+      show_author: true        # Show author or not: true false, default: true
 
 ```
 
@@ -125,13 +129,21 @@ The plugin supports deep customization, such as icon style, font style, theme co
 - Style & Theme: `docs/assets/document_dates/user.config.css`
 - Properties & Animations: `docs/assets/document_dates/user.config.js`
 - Localized languages: `docs/assets/document_dates/languages/` , refer to the template file `en.json` for any additions or modifications
+- timeago.js localization: `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
+        ```yaml
+        extra_javascript:
+          - assets/document_dates/core/timeago.full.min.js
+          - assets/document_dates/core/timeago-load.js
+        ```
 
 ## Other Tips
 
 - In order to get the exact creation time, a separate cache file is used to store the creation time of the file, located in the doc folder (hidden by default), please don't delete it:
     - `docs/.dates_cache.jsonl`, cache file
-    - `docs/.gitattributes`, merge mechanism for cache file in case of multi-person collaboration
-- The Git Hooks mechanism is used to automatically trigger the storing of the cache (every time executes a git commit), and the cached file is automatically committed along with it. In addition, the installation of Git Hooks is automatically triggered when the plugin is installed, without any manual intervention!
+    - `docs/.gitattributes`, merge mechanism for cache file
+- The Git Hooks mechanism is used to automatically trigger the storing of the cache (on each git commit), and the cached file is automatically committed along with it. In addition, the installation of Git Hooks is automatically triggered when the plugin is installed, without any manual intervention!
 
 <br />
 
@@ -147,9 +159,13 @@ A dispensable, insignificant little plug-in, friends who have time can take a lo
     - Method 2: You can cache the original time, and then read the cache subsequently. The cache can be in Front Matter of the source document or in a separate file, I chose the latter. Storing in Front Matter makes sense and is simple, but this will modify the source content of the document, although it doesn't have any impact on the body, but I still want to ensure the originality of the data!
 - **Difficulty**:
     1. When to read and store original time? This is just a plugin for mkdocs, with very limited access and permissions, mkdocs provides only build and serve, so in case a user commits directly without executing build or serve (e.g., when using a CI/CD build system), then you won't be able to retrieve the time information of the file, not to mention caching it!
-        - Let's take a straight shot: the Git Hooks mechanism was found, prompted by the AI, which can trigger a custom script when a specific action occurs, such as every time commit is performed
-    2. How can I ensure that a single cache file does not conflict when collaborating with multi-person?
-        - My solution: use JSONL (JSON Lines) instead of JSON, and with the merge strategy 'merge=union'
+        - Let's take a straight shot: the Git Hooks mechanism was found, prompted by the AI, which can trigger a custom script when a specific git action occurs, such as every time commit is performed
+    2. How to install Git Hooks automatically? When and how are they triggered? Installing packages from PyPI via pip doesn't have a standard post-install hook mechanism
+        - Workaround: After analyzing the flow of pip installing packages from PyPI, I found that when compiling and installing through the source package (sdist), setuptools will be called to handle it, so we can find a way to implant the installation script in the process of setuptools, i.e., we can add a custom script in setup.py
+    3. How to design a cross-platform hook? To execute a python script, we need to explicitly specify the python interpreter, and the user's python environment varies depending on the operating system, the way python is installed, and the configuration, so how can we ensure that it works properly in all environments?
+        - Solution: I considered using a shell script, but since I'd have to call back to python eventually, it's easier to use a python script. We can detect the user's python environment when the hook is installed, and then dynamically set the hook's shebang line to set the correct python interpreter
+    4. How can I ensure that a single cache file does not conflict when collaborating with multi-person?
+        - Workaround: use JSONL (JSON Lines) instead of JSON, and with the merge strategy 'merge=union'
 - **Improve**:
     - Since it has been re-developed, it will be designed in the direction of **excellent products**, and the pursuit of the ultimate **ease of use, simplicity and personalization**
         - Ease of use: don't let users do things manually if you can, e.g., auto-install Git Hooks, auto-cache, auto-commit, provide customized templates, etc
@@ -157,4 +173,4 @@ A dispensable, insignificant little plug-in, friends who have time can take a lo
         - Personalization: almost everything can be customized, whether it's icons, styles, themes, or features, it's all fully customizable
     - In addition, it has good compatibility and extensibility, and works well in WIN7, mobile devices, old Safari, etc
 - **The Last Secret**:
-    - I'm not a programmer, my main job is marketing, can you believe it? (Feel free to leave a comment)
+    - Programming is a hobby, and I'm a marketer of 8 years (Feel free to leave a comment)

{mkdocs_document_dates-3.1.1 → mkdocs_document_dates-3.1.3}/README.md

@@ -47,15 +47,15 @@ plugins:
   - document-dates:
       position: top            # Display position: top (after title)  bottom (end of document), default: bottom
       type: date               # Date type: date  datetime  timeago, default: date
-      locale: en               # Localization: zh zh_tw en es fr de ar ja ko ru, default: en
-      date_format: '%Y-%m-%d'  # Date format, Supports all Python datetime format strings, e.g., %Y-%m-%d, %b %d, %Y, etc
+      locale: en               # Localization: zh zh_TW en es fr de ar ja ko ru, default: en
+      date_format: '%Y-%m-%d'  # Date format, supports all python datetime format strings, e.g., %Y-%m-%d, %b %d, %Y, etc
       time_format: '%H:%M:%S'  # Time format (valid only if type=datetime)
       exclude:                 # List of excluded files
         - temp.md              # Exclude specific file
         - private/*            # Exclude all files in private directory, including subdirectories
         - drafts/*.md          # Exclude all markdown files in the current directory drafts, but not subdirectories
       
-      show_author: true        # Whether to display author: true false, default: true
+      show_author: true        # Show author or not: true false, default: true
 
 ```
 
@@ -102,13 +102,21 @@ The plugin supports deep customization, such as icon style, font style, theme co
 - Style & Theme: `docs/assets/document_dates/user.config.css`
 - Properties & Animations: `docs/assets/document_dates/user.config.js`
 - Localized languages: `docs/assets/document_dates/languages/` , refer to the template file `en.json` for any additions or modifications
+- timeago.js localization: `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
+        ```yaml
+        extra_javascript:
+          - assets/document_dates/core/timeago.full.min.js
+          - assets/document_dates/core/timeago-load.js
+        ```
 
 ## Other Tips
 
 - In order to get the exact creation time, a separate cache file is used to store the creation time of the file, located in the doc folder (hidden by default), please don't delete it:
     - `docs/.dates_cache.jsonl`, cache file
-    - `docs/.gitattributes`, merge mechanism for cache file in case of multi-person collaboration
-- The Git Hooks mechanism is used to automatically trigger the storing of the cache (every time executes a git commit), and the cached file is automatically committed along with it. In addition, the installation of Git Hooks is automatically triggered when the plugin is installed, without any manual intervention!
+    - `docs/.gitattributes`, merge mechanism for cache file
+- The Git Hooks mechanism is used to automatically trigger the storing of the cache (on each git commit), and the cached file is automatically committed along with it. In addition, the installation of Git Hooks is automatically triggered when the plugin is installed, without any manual intervention!
 
 <br />
 
@@ -124,9 +132,13 @@ A dispensable, insignificant little plug-in, friends who have time can take a lo
     - Method 2: You can cache the original time, and then read the cache subsequently. The cache can be in Front Matter of the source document or in a separate file, I chose the latter. Storing in Front Matter makes sense and is simple, but this will modify the source content of the document, although it doesn't have any impact on the body, but I still want to ensure the originality of the data!
 - **Difficulty**:
     1. When to read and store original time? This is just a plugin for mkdocs, with very limited access and permissions, mkdocs provides only build and serve, so in case a user commits directly without executing build or serve (e.g., when using a CI/CD build system), then you won't be able to retrieve the time information of the file, not to mention caching it!
-        - Let's take a straight shot: the Git Hooks mechanism was found, prompted by the AI, which can trigger a custom script when a specific action occurs, such as every time commit is performed
-    2. How can I ensure that a single cache file does not conflict when collaborating with multi-person?
-        - My solution: use JSONL (JSON Lines) instead of JSON, and with the merge strategy 'merge=union'
+        - Let's take a straight shot: the Git Hooks mechanism was found, prompted by the AI, which can trigger a custom script when a specific git action occurs, such as every time commit is performed
+    2. How to install Git Hooks automatically? When and how are they triggered? Installing packages from PyPI via pip doesn't have a standard post-install hook mechanism
+        - Workaround: After analyzing the flow of pip installing packages from PyPI, I found that when compiling and installing through the source package (sdist), setuptools will be called to handle it, so we can find a way to implant the installation script in the process of setuptools, i.e., we can add a custom script in setup.py
+    3. How to design a cross-platform hook? To execute a python script, we need to explicitly specify the python interpreter, and the user's python environment varies depending on the operating system, the way python is installed, and the configuration, so how can we ensure that it works properly in all environments?
+        - Solution: I considered using a shell script, but since I'd have to call back to python eventually, it's easier to use a python script. We can detect the user's python environment when the hook is installed, and then dynamically set the hook's shebang line to set the correct python interpreter
+    4. How can I ensure that a single cache file does not conflict when collaborating with multi-person?
+        - Workaround: use JSONL (JSON Lines) instead of JSON, and with the merge strategy 'merge=union'
 - **Improve**:
     - Since it has been re-developed, it will be designed in the direction of **excellent products**, and the pursuit of the ultimate **ease of use, simplicity and personalization**
         - Ease of use: don't let users do things manually if you can, e.g., auto-install Git Hooks, auto-cache, auto-commit, provide customized templates, etc
@@ -134,4 +146,4 @@ A dispensable, insignificant little plug-in, friends who have time can take a lo
         - Personalization: almost everything can be customized, whether it's icons, styles, themes, or features, it's all fully customizable
     - In addition, it has good compatibility and extensibility, and works well in WIN7, mobile devices, old Safari, etc
 - **The Last Secret**:
-    - I'm not a programmer, my main job is marketing, can you believe it? (Feel free to leave a comment)
+    - Programming is a hobby, and I'm a marketer of 8 years (Feel free to leave a comment)

{mkdocs_document_dates-3.1.1 → mkdocs_document_dates-3.1.3}/mkdocs_document_dates/cache_manager.py

@@ -1,5 +1,4 @@
 import os
-import sys
 import json
 import logging
 import platform
@@ -14,13 +13,13 @@ logging.basicConfig(
 )
 
 def find_mkdocs_projects():
+    projects = []
     try:
         git_root = Path(subprocess.check_output(
             ['git', 'rev-parse', '--show-toplevel'],
             text=True, encoding='utf-8'
         ).strip())
 
-        projects = []
         # 遍历 git_root 及子目录, 寻找 mkdocs.yml 文件
         for config_file in git_root.rglob('mkdocs.y*ml'):
             if config_file.name.lower() in ('mkdocs.yml', 'mkdocs.yaml'):
@@ -28,13 +27,12 @@ def find_mkdocs_projects():
 
         if not projects:
             logging.info("No MkDocs projects found in the repository")
-        return projects
     except subprocess.CalledProcessError as e:
         logging.error(f"Failed to find the Git repository root: {e}")
-        return []
     except Exception as e:
         logging.error(f"Unexpected error while searching for MkDocs projects: {e}")
-        return []
+    
+    return projects
 
 def get_file_creation_time(file_path):
     try:
@@ -66,29 +64,30 @@ def get_git_first_commit_time(file_path):
     return None
 
 def setup_gitattributes(docs_dir):
-    gitattributes_path = docs_dir / '.gitattributes'
-    union_config_line = ".dates_cache.jsonl merge=union"
     updated = False
-    
-    if gitattributes_path.exists():
-        with open(gitattributes_path, 'r', encoding='utf-8') as f:
-            content = f.read()
-        
-        if union_config_line not in content:
-            with open(gitattributes_path, 'a', encoding='utf-8') as f:
-                f.write(f"\n{union_config_line}\n")
+    try:
+        gitattributes_path = docs_dir / '.gitattributes'
+        union_config_line = ".dates_cache.jsonl merge=union"        
+        if gitattributes_path.exists():
+            with open(gitattributes_path, 'r', encoding='utf-8') as f:
+                content = f.read()
+            
+            if union_config_line not in content:
+                with open(gitattributes_path, 'a', encoding='utf-8') as f:
+                    f.write(f"\n{union_config_line}\n")
+                updated = True
+        else:
+            with open(gitattributes_path, 'w', encoding='utf-8') as f:
+                f.write(f"{union_config_line}\n")
             updated = True
-    else:
-        with open(gitattributes_path, 'w', encoding='utf-8') as f:
-            f.write(f"{union_config_line}\n")
-        updated = True
-    
-    if updated:
-        try:
+        
+        if updated:
             subprocess.run(["git", "add", str(gitattributes_path)], check=True)
             logging.info(f"Updated .gitattributes file: {gitattributes_path}")
-        except subprocess.CalledProcessError as e:
-            logging.error(f"Failed to add .gitattributes to git: {e}")
+    except (IOError, OSError) as e:
+        logging.error(f"Failed to read/write .gitattributes file: {e}")
+    except Exception as e:
+        logging.error(f"Failed to add .gitattributes to git: {e}")
     
     return updated
 
@@ -145,87 +144,90 @@ def write_jsonl_cache(jsonl_file, dates_cache, tracked_files):
 
 def update_cache():
     global_updated = False
-    for project_dir in find_mkdocs_projects():
-        project_updated = False
-
-        docs_dir = project_dir / 'docs'
-        if not docs_dir.exists():
-            logging.error(f"Document directory does not exist: {docs_dir}")
-            continue
+    try:
+        for project_dir in find_mkdocs_projects():
+            try:
+                project_updated = False
 
-        # 设置.gitattributes文件
-        gitattributes_updated = setup_gitattributes(docs_dir)
-        if gitattributes_updated:
-            global_updated = True
+                docs_dir = project_dir / 'docs'
+                if not docs_dir.exists():
+                    logging.error(f"Document directory does not exist: {docs_dir}")
+                    continue
 
-        try:
-            # 获取docs目录下已跟踪(tracked)的markdown文件
-            cmd = ["git", "ls-files", "*.md"]
-            result = subprocess.run(cmd, cwd=docs_dir, capture_output=True, text=True, check=True)
-            tracked_files = result.stdout.splitlines() if result.stdout else []
-            
-            if not tracked_files:
-                logging.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)
+                # 设置.gitattributes文件
+                gitattributes_updated = setup_gitattributes(docs_dir)
+                if gitattributes_updated:
+                    global_updated = True
 
-            # 读取新的JSONL缓存文件（如果存在）
-            jsonl_cache_file = docs_dir / '.dates_cache.jsonl'
-            jsonl_dates_cache = read_jsonl_cache(jsonl_cache_file)
-            
-            # 根据 git已跟踪的文件来更新
-            for file_path in tracked_files:
-                try:
-                    rel_path = file_path
-                    full_path = docs_dir / rel_path
-                    
-                    # 如果文件已在JSONL缓存中，跳过
-                    if rel_path in jsonl_dates_cache:
+                # 获取docs目录下已跟踪(tracked)的markdown文件
+                cmd = ["git", "ls-files", "*.md"]
+                result = subprocess.run(cmd, cwd=docs_dir, capture_output=True, text=True, check=True)
+                tracked_files = result.stdout.splitlines() if result.stdout else []
+                
+                if not tracked_files:
+                    logging.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 file_path in tracked_files:
+                    try:
+                        rel_path = file_path
+                        full_path = docs_dir / rel_path
+                        
+                        # 如果文件已在JSONL缓存中，跳过
+                        if rel_path in jsonl_dates_cache:
+                            continue
+                        
+                        # 处理新文件或迁移旧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)
+                            if not jsonl_cache_file.exists() and not json_cache_file.exists():
+                                git_time = get_git_first_commit_time(full_path)
+                                if git_time is not None:
+                                    created_time = min(created_time, git_time)
+                            jsonl_dates_cache[rel_path] = {
+                                "created": created_time.isoformat()
+                            }
+                            project_updated = True
+                    except Exception as e:
+                        logging.error(f"Error processing file {file_path}: {e}")
                         continue
-                    
-                    # 处理新文件或迁移旧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)
-                        if not jsonl_cache_file.exists() and not json_cache_file.exists():
-                            git_time = get_git_first_commit_time(full_path)
-                            if git_time is not None:
-                                created_time = min(created_time, git_time)
-                        jsonl_dates_cache[rel_path] = {
-                            "created": created_time.isoformat()
-                        }
-                        project_updated = True
-                except Exception as e:
-                    logging.error(f"Error processing file {file_path}: {e}")
-
-            # 标记删除不再跟踪的文件
-            files_to_remove = set(jsonl_dates_cache.keys()) - set(tracked_files)
-            if files_to_remove:
-                project_updated = True
-                logging.info(f"Removing {len(files_to_remove)} untracked files from cache")
-
-            # 如果有更新，写入JSONL缓存文件
-            if project_updated or not jsonl_cache_file.exists():
-                if write_jsonl_cache(jsonl_cache_file, jsonl_dates_cache, tracked_files):
-                    global_updated = True
-            else:
-                logging.info(f"No updates needed for {jsonl_cache_file}")
 
-        except subprocess.CalledProcessError as e:
-            logging.error(f"Failed to execute git command: {e}")
-            continue
+                # 标记删除不再跟踪的文件
+                files_to_remove = set(jsonl_dates_cache.keys()) - set(tracked_files)
+                if files_to_remove:
+                    project_updated = True
+                    logging.info(f"Removing {len(files_to_remove)} untracked files from cache")
+
+                # 如果有更新，写入JSONL缓存文件
+                if project_updated or not jsonl_cache_file.exists():
+                    if write_jsonl_cache(jsonl_cache_file, jsonl_dates_cache, tracked_files):
+                        global_updated = True
+                else:
+                    logging.info(f"No updates needed for {jsonl_cache_file}")
+            except subprocess.CalledProcessError as e:
+                logging.error(f"Failed to execute git command: {e}")
+                continue
+            except Exception as e:
+                logging.error(f"Error processing project directory {project_dir}: {e}")
+                continue
+
+    except Exception as e:
+        logging.error(f"Unexpected error in update_cache: {e}")
     
     return global_updated
 
 
 if __name__ == "__main__":
-    try:
-        update_cache()
-    except Exception as e:
-        logging.error(f"Hook execution failed: {e}")
-        sys.exit(1)
+    update_cache()

mkdocs_document_dates-3.1.3/mkdocs_document_dates/hooks/pre-commit

@@ -0,0 +1,11 @@
+#!/usr/bin/env python3
+
+try:
+    from mkdocs_document_dates.cache_manager import update_cache
+except Exception:
+    import sys
+    # 正常退出（0 状态码），不影响 git 的后续动作
+    sys.exit(0)
+
+if __name__ == "__main__":
+    update_cache()

{mkdocs_document_dates-3.1.1 → mkdocs_document_dates-3.1.3}/mkdocs_document_dates/hooks_installer.py

@@ -23,7 +23,7 @@ def check_python_version(interpreter):
             [interpreter, "-c", "import sys; print(sys.version_info >= (3, 7))"],
             capture_output=True, text=True, check=False
         )
-        if result.returncode == 0 and result.stdout.strip() == 'True':
+        if result.returncode == 0 and result.stdout.strip().lower() == 'true':
             return True
         else:
             logging.warning(f"Low python version, requires python_requires >=3.7")
@@ -47,7 +47,7 @@ def check_git_available():
     try:
         subprocess.run(['git', '--version'], check=True, capture_output=True, encoding='utf-8')
         return True
-    except (subprocess.CalledProcessError, FileNotFoundError):
+    except Exception:
         logging.warning("Git not detected, skip hooks installation")
         return False
 
@@ -95,7 +95,7 @@ def configure_git_hooks(hooks_dir):
         )
         logging.info(f"Git hooks successfully installed in: {hooks_dir}")
         return True
-    except subprocess.CalledProcessError as e:
+    except Exception as e:
         logging.error(f"Failed to set git hooks path: {str(e)}")
         return False