mkdocs-document-dates 2.4.0__tar.gz → 3.0.1__tar.gz

{mkdocs_document_dates-2.4.0 → mkdocs_document_dates-3.0.1}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: mkdocs-document-dates
-Version: 2.4.0
-Summary: A MkDocs plugin for displaying accurate document creation and last modification dates.
+Version: 3.0.1
+Summary: A MkDocs plugin for displaying the exact creation date and last modification date of markdown documents.
 Home-page: https://github.com/jaywhj/mkdocs-document-dates
 Author: Aaron Wang
 Classifier: Programming Language :: Python :: 3
@@ -27,20 +27,27 @@ English | [简体中文](README_zh.md)
 
 
 
-A MkDocs plugin for displaying <mark>accurate</mark> document creation and last modification dates.
+A MkDocs plugin for displaying the <mark>exact</mark> creation date and last modification date of markdown documents.
 
 ## Features
 
 - **No Git dependency**, uses filesystem timestamps directly
 - Supports manual date specification in `Front Matter`
-- Cross-platform support (Windows, macOS, Linux)
 - Support for multiple time formats (date, datetime, timeago)
-- Flexible display position (top or bottom)
 - Support for document exclusion mode
-- Material Design icons, Elegant styling
-- Lightweight with no extra dependencies
-- Multi-language support
+- Flexible display position (top or bottom)
+- Material style icons, elegant styling (Customizable)
+- Supports Tooltip Hover Tips
+  - Intelligent repositioning to always float optimally in view
+  - Supports automatic theme switching following Material's light/dark color scheme
+  - Support for customizing themes, styles, animations
+  - Compatible with mouse, keyboard and **touch** (mobile) to trigger hover
 - Support for CI/CD build systems (e.g. Github Actions)
+- Multi-language support, cross-platform support (Windows, macOS, Linux)
+
+## Showcases
+
+![render](render.gif)
 
 ## Installation
 
@@ -50,7 +57,7 @@ pip install mkdocs-document-dates
 
 ## Configuration
 
-Just add the plugin to your mkdocs.yml:
+Just add the plugin to your `mkdocs.yml`:
 
 ```yaml
 plugins:
@@ -62,12 +69,12 @@ Or, customize the configuration:
 ```yaml
 plugins:
   - document-dates:
-      type: date               # Date type: date | datetime | timeago, default: date
+      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
+      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)
-      position: bottom         # Display position: top (after title) | bottom (end of document), default: bottom
-      exclude:                 # List of file patterns to exclude
+      position: bottom         # Display position: top (after title)  bottom (end of document), default: bottom
+      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
@@ -86,40 +93,32 @@ modified: 2025-02-23
 # Document Title
 ```
 
-- `created` can be replaced by any of the following fields: `created, date, creation_date, created_at, date_created`
-- `modified` can be replaced by any of the following fields: `modified, updated, last_modified, updated_at, date_modified, last_update`
-
-## Configuration Options
-
-- **type** : Date type (default: `date` )
-  - `date` : Display date only
-  - `datetime` : Display date and time
-  - `timeago` : Display relative time (e.g., 2 minutes ago)
-- **locale** : Localization (default: `en` )
-  - Supports: `zh zh_tw en es fr de ar ja ko ru`
-- **date_format** : Date format (default: `%Y-%m-%d`)
-  - Supports all Python datetime format strings, e.g., %Y-%m-%d, %b %d, %Y, etc.
-- **time_format** : Time format (default: `%H:%M:%S`)
-- **position** : Display position (default: `bottom`)
-  - `top` : Display after the first heading
-  - `bottom` : Display at the end of the document
-- **exclude** : File exclusion list (default: [] )
-  - Supports glob patterns, e.g., ["private/\*", "temp.md", "drafts/\*.md"]
+- `created` can be replaced with: `created, date, creation_date, created_at, date_created`
+- `modified` can be replaced with: `modified, updated, last_modified, updated_at, date_modified, last_update`
+
+## Customization
+
+This plugin supports deep customization, just modify the code in the corresponding file:
+
+- Style & Theme: `docs/assets/document_dates/document-dates.config.css`
+- Properties & Animations: `docs/assets/document_dates/document-dates.config.js`
+
+Tip: If you want to restore the default effect, just delete this file and rebuild your project
 
 ## Tips
 
-- 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:
+- It still works when using CI/CD build systems (e.g. Github Actions), here's how it works:
+    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
     ```
-    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
+    2. Then update your Markdown document in `docs` 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
         - 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:
+    4. Finally, run git push, and you can see that the `.dates_cache.json` file also exists in the docs directory in the GitHub repository, which means success!
+- Priority for datetime reads:
     - `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-3.0.1/README.md

@@ -0,0 +1,101 @@
+# mkdocs-document-dates
+
+English | [简体中文](README_zh.md)
+
+
+
+A MkDocs plugin for displaying the <mark>exact</mark> creation date and last modification date of markdown documents.
+
+## Features
+
+- **No Git dependency**, uses filesystem timestamps directly
+- Supports manual date specification in `Front Matter`
+- Support for multiple time formats (date, datetime, timeago)
+- Support for document exclusion mode
+- Flexible display position (top or bottom)
+- Material style icons, elegant styling (Customizable)
+- Supports Tooltip Hover Tips
+  - Intelligent repositioning to always float optimally in view
+  - Supports automatic theme switching following Material's light/dark color scheme
+  - Support for customizing themes, styles, animations
+  - Compatible with mouse, keyboard and **touch** (mobile) to trigger hover
+- Support for CI/CD build systems (e.g. Github Actions)
+- Multi-language support, cross-platform support (Windows, macOS, Linux)
+
+## Showcases
+
+![render](render.gif)
+
+## Installation
+
+```bash
+pip install mkdocs-document-dates
+```
+
+## Configuration
+
+Just add the plugin to your `mkdocs.yml`:
+
+```yaml
+plugins:
+  - document-dates
+```
+
+Or, customize the configuration:
+
+```yaml
+plugins:
+  - document-dates:
+      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
+      time_format: '%H:%M:%S'  # Time format (valid only if type=datetime)
+      position: bottom         # Display position: top (after title)  bottom (end of document), default: bottom
+      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
+```
+
+## Manual Date Specification
+
+You can also manually specify the date of a Markdown document in its `Front Matter` :
+
+```yaml
+---
+created: 2023-01-01
+modified: 2025-02-23
+---
+
+# Document Title
+```
+
+- `created` can be replaced with: `created, date, creation_date, created_at, date_created`
+- `modified` can be replaced with: `modified, updated, last_modified, updated_at, date_modified, last_update`
+
+## Customization
+
+This plugin supports deep customization, just modify the code in the corresponding file:
+
+- Style & Theme: `docs/assets/document_dates/document-dates.config.css`
+- Properties & Animations: `docs/assets/document_dates/document-dates.config.js`
+
+Tip: If you want to restore the default effect, just delete this file and rebuild your project
+
+## Tips
+
+- It still works when using CI/CD build systems (e.g. Github Actions), here's how it works:
+    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
+    ```
+    2. Then update your Markdown document in `docs` 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
+        - Make sure you have installed python3 ahead of time and set environment variables
+    4. Finally, run git push, and you can see that the `.dates_cache.json` file also exists in the docs directory in the GitHub repository, which means success!
+- Priority for datetime reads:
+    - `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.4.0 → mkdocs_document_dates-3.0.1}/mkdocs_document_dates/hooks/pre-commit

@@ -5,9 +5,16 @@ import sys
 import json
 import platform
 import subprocess
+import logging
 from datetime import datetime
 from pathlib import Path
 
+# 配置日志等级 (INFO WARNING ERROR)
+logging.basicConfig(
+    level=logging.WARNING,
+    format='%(levelname)s - %(message)s'
+)
+
 def find_mkdocs_projects():
     try:
         git_root = Path(subprocess.check_output(
@@ -20,9 +27,14 @@ def find_mkdocs_projects():
             if config_file.name.lower() in ('mkdocs.yml', 'mkdocs.yaml'):
                 projects.append(config_file.parent)
 
+        if not projects:
+            logging.info("No MkDocs projects found in the repository")
         return projects
     except subprocess.CalledProcessError as e:
-        print(f"Failed to find the Git repository root: {e}", file=sys.stderr)
+        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 []
 
 def get_file_dates(file_path):
@@ -38,11 +50,14 @@ def get_file_dates(file_path):
                 created = datetime.fromtimestamp(stat.st_birthtime)
             except AttributeError:
                 created = datetime.fromtimestamp(stat.st_ctime)
-        else:  # Linux 和其他系统
+                logging.warning(f"Birth time not available for {file_path}, using ctime instead")
+        else:  # Linux and other systems
             created = modified
+            logging.info(f"Creation time not supported on {system}, using modification time for {file_path}")
 
         return created.isoformat(), modified.isoformat()
-    except (OSError, ValueError):
+    except (OSError, ValueError) as e:
+        logging.error(f"Failed to get file dates for {file_path}: {e}")
         current_time = datetime.now()
         return current_time.isoformat(), current_time.isoformat()
 
@@ -50,12 +65,16 @@ def update_dates_cache():
     for project_dir in find_mkdocs_projects():
         docs_dir = project_dir / 'docs'
         if not docs_dir.exists():
-            print(f"Document directory does not exist: {docs_dir}")
+            logging.error(f"Document directory does not exist: {docs_dir}")
             continue
 
         dates_cache = {}
         md_files = list(docs_dir.rglob("*.md"))
         
+        if not md_files:
+            logging.info(f"No markdown files found in {docs_dir}")
+            continue
+
         for md_file in md_files:
             try:
                 rel_path = str(md_file.relative_to(docs_dir))
@@ -65,24 +84,28 @@ def update_dates_cache():
                     "modified": modified
                 }
             except Exception as e:
-                print(f"Error processing file {md_file}: {e}")
+                logging.error(f"Error processing file {md_file}: {e}")
 
         if not dates_cache:
+            logging.warning(f"No valid dates cache generated for {project_dir}")
             continue
 
         cache_file = docs_dir / '.dates_cache.json'
         try:
-            with open(cache_file, "w") as f:
+            with open(cache_file, "w", encoding='utf-8') as f:
                 json.dump(dates_cache, f, indent=2, ensure_ascii=False)
             subprocess.run(["git", "add", str(cache_file)], check=True)
-            # print(f"The cache file {cache_file} has been updated")
-        except Exception as e:
-            print(f"Error writing to cache file: {e}", file=sys.stderr)
+            logging.info(f"Successfully updated cache file: {cache_file}")
+        except (IOError, json.JSONDecodeError) as e:
+            logging.error(f"Failed to write cache file {cache_file}: {e}")
+            raise
+        except subprocess.CalledProcessError as e:
+            logging.error(f"Failed to add cache file to git: {e}")
             raise
 
 if __name__ == "__main__":
     try:
         update_dates_cache()
     except Exception as e:
-        print(f"Hook execution error: {e}", file=sys.stderr)
+        logging.error(f"Hook execution failed: {e}")
         sys.exit(1)

{mkdocs_document_dates-2.4.0 → mkdocs_document_dates-3.0.1}/mkdocs_document_dates/hooks_installer.py

@@ -1,10 +1,17 @@
 import os
 import sys
 import shutil
+import logging
 import subprocess
 from pathlib import Path
 import platform
 
+# 配置日志等级 (INFO WARNING ERROR)
+logging.basicConfig(
+    level=logging.WARNING,
+    format='%(levelname)s: %(message)s'
+)
+
 def get_config_dir():
     if platform.system().lower().startswith('win'):
         return Path(os.getenv('APPDATA', str(Path.home() / 'AppData' / 'Roaming')))
@@ -17,7 +24,7 @@ def install():
         try:
             subprocess.run(['git', '--version'], check=True, capture_output=True, encoding='utf-8')
         except (subprocess.CalledProcessError, FileNotFoundError):
-            print("Tip: Git not detected, skip hooks installation")
+            logging.warning("Git not detected, skip hooks installation")
             return False
         
         # 准备配置目录
@@ -25,27 +32,23 @@ def install():
         try:
             config_dir.mkdir(parents=True, exist_ok=True)
         except PermissionError:
-            print(f"Error: No permission to create directory: {config_dir}")
+            logging.error(f"No permission to create directory: {config_dir}")
             return False
         except Exception as e:
-            print(f"Error: Failed to create directory: {config_dir}, reason: {e}")
+            logging.error(f"Failed to create directory {config_dir}: {str(e)}")
             return False
 
         hook_path = config_dir / 'pre-commit'
-
-        # 复制 hook 文件到配置目录
         source_hook = Path(__file__).parent / 'hooks' / 'pre-commit'
-        if not source_hook.exists():
-            print(f"Error: Source hook file does not exist: {source_hook}")
-            return False
 
+        # 复制 hook 文件到配置目录
         try:
             shutil.copy2(source_hook, hook_path)
         except PermissionError:
-            print(f"Error: No permission to copy file to: {hook_path}")
+            logging.error(f"No permission to copy file to: {hook_path}")
             return False
         except Exception as e:
-            print(f"Error: Failed to copy file, reason: {e}")
+            logging.error(f"Failed to copy file to {hook_path}: {str(e)}")
             return False
 
         # 设置文件权限
@@ -53,20 +56,24 @@ def install():
             os.chmod(config_dir, 0o755)
             os.chmod(hook_path, 0o755)
         except OSError as e:
-            print(f"Warning: Error setting permissions: {e}")
+            logging.warning(f"Failed to set file permissions: {str(e)}")
 
         # 配置全局 git hooks 路径
         try:
-            subprocess.run(['git', 'config', '--global', 'core.hooksPath', 
-                          str(config_dir)], check=True, encoding='utf-8')
-            # print(f"Git hooks are installed in the: {config_dir}")
+            subprocess.run(
+                ['git', 'config', '--global', 'core.hooksPath', str(config_dir)],
+                check=True,
+                capture_output=True,
+                encoding='utf-8'
+            )
+            logging.info(f"Git hooks successfully installed in: {config_dir}")
             return True
         except subprocess.CalledProcessError as e:
-            print(f"Error: Setting git hooks path failed: {e}")
+            logging.error(f"Failed to set git hooks path: {str(e)}")
             return False
             
     except Exception as e:
-        print(f"Error installing hooks: {e}")
+        logging.error(f"Unexpected error during hooks installation: {str(e)}")
         return False
 
 if __name__ == '__main__':