mkdocs-ultralytics-plugin 0.2.0__tar.gz → 0.2.2__tar.gz

{mkdocs_ultralytics_plugin-0.2.0 → mkdocs_ultralytics_plugin-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs-ultralytics-plugin
-Version: 0.2.0
+Version: 0.2.2
 Summary: An MkDocs plugin that provides Ultralytics Docs customizations at https://docs.ultralytics.com.
 Author-email: Glenn Jocher <hello@ultralytics.com>
 Maintainer-email: Ultralytics <hello@ultralytics.com>

{mkdocs_ultralytics_plugin-0.2.0 → mkdocs_ultralytics_plugin-0.2.2}/mkdocs_ultralytics_plugin.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs-ultralytics-plugin
-Version: 0.2.0
+Version: 0.2.2
 Summary: An MkDocs plugin that provides Ultralytics Docs customizations at https://docs.ultralytics.com.
 Author-email: Glenn Jocher <hello@ultralytics.com>
 Maintainer-email: Ultralytics <hello@ultralytics.com>

{mkdocs_ultralytics_plugin-0.2.0 → mkdocs_ultralytics_plugin-0.2.2}/plugin/__init__.py

@@ -1,6 +1,6 @@
 # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license
 
-__version__ = "0.2.0"
+__version__ = "0.2.2"
 
 from .main import MetaPlugin
 from .postprocess import postprocess_site

{mkdocs_ultralytics_plugin-0.2.0 → mkdocs_ultralytics_plugin-0.2.2}/plugin/main.py

@@ -2,9 +2,12 @@
 
 from __future__ import annotations
 
+from pathlib import Path
+
 from mkdocs.config import config_options
 from mkdocs.plugins import BasePlugin
 
+import plugin.processor as processor
 from plugin.processor import process_html
 
 
@@ -26,6 +29,22 @@ class MetaPlugin(BasePlugin):
         ("add_copy_llm", config_options.Type(bool, default=True)),
     )
 
+    def __init__(self):
+        super().__init__()
+        self.git_repo_url = None
+        self.git_data = None
+
+    def on_config(self, config):
+        """Prepare git metadata once for all pages if authors/JSON-LD are enabled."""
+        if not self.config.get("enabled", True):
+            return config
+
+        if self.config.get("add_authors") or self.config.get("add_json_ld"):
+            docs_dir = Path(config["docs_dir"])
+            md_files = [str(p) for p in docs_dir.rglob("*.md")] if docs_dir.exists() else []
+            self.git_repo_url, self.git_data = processor.build_git_map(md_files)
+        return config
+
     def on_post_page(self, output: str, page, config) -> str:
         """Enhance HTML output by delegating to shared processor."""
         if not self.config["enabled"]:
@@ -47,6 +66,8 @@ class MetaPlugin(BasePlugin):
                 page_url=page_url,
                 title=title,
                 src_path=page.file.abs_src_path,
+                git_data=self.git_data,
+                repo_url=self.git_repo_url,
                 default_image=self.config["default_image"],
                 default_author=self.config["default_author"],
                 keywords=keywords,

{mkdocs_ultralytics_plugin-0.2.0 → mkdocs_ultralytics_plugin-0.2.2}/plugin/postprocess.py

@@ -3,8 +3,15 @@
 
 from __future__ import annotations
 
+from collections.abc import Callable
 from pathlib import Path
 
+try:
+    from ultralytics.utils import TQDM  # progress bars
+except ImportError:
+    TQDM = None
+
+import plugin.processor as processor
 from plugin.processor import process_html
 
 
@@ -12,6 +19,8 @@ def process_html_file(
     html_path: Path,
     site_dir: Path,
     md_index: dict[str, str],
+    git_data: dict[str, dict[str, str | dict]] | None,
+    repo_url: str | None,
     site_url: str = "",
     default_image: str | None = None,
     default_author: str | None = None,
@@ -24,6 +33,7 @@ def process_html_file(
     add_css: bool = True,
     add_copy_llm: bool = True,
     verbose: bool = False,
+    log: Callable[[str], None] | None = print,
 ) -> bool:
     """Process a single HTML file by delegating to shared processor.
 
@@ -35,8 +45,8 @@ def process_html_file(
     try:
         html = html_path.read_text(encoding="utf-8")
     except (UnicodeDecodeError, FileNotFoundError) as e:
-        if verbose:
-            print(f"Error reading {html_path}: {e}")
+        if verbose and log:
+            log(f"Error reading {html_path}: {e}")
         return False
 
     soup = BeautifulSoup(html, "html.parser")
@@ -65,6 +75,8 @@ def process_html_file(
         page_url=page_url,
         title=title,
         src_path=src_path,
+        git_data=git_data,
+        repo_url=repo_url,
         default_image=default_image,
         default_author=default_author,
         keywords=keywords,
@@ -81,12 +93,10 @@ def process_html_file(
     # Write back
     try:
         html_path.write_text(processed_html, encoding="utf-8")
-        if verbose:
-            print(f"Processed: {html_path.relative_to(site_dir)}")
         return True
     except (OSError, PermissionError) as e:
-        if verbose:
-            print(f"Error writing {html_path}: {e}")
+        if verbose and log:
+            log(f"Error writing {html_path}: {e}")
         return False
 
 
@@ -129,11 +139,21 @@ def postprocess_site(
     print(f"Processing {len(html_files)} HTML files in {site_dir}")
 
     processed = 0
-    for html_file in html_files:
+    repo_url = None
+    git_data = None
+    if (add_authors or add_json_ld) and md_index:
+        repo_url, git_data = processor.build_git_map(list(md_index.values()))
+
+    progress = TQDM(html_files, desc="Postprocessing", unit="file", disable=not verbose) if TQDM else None
+    log_fn = (progress.write if verbose and progress else print) if verbose else None
+    iterator = progress if progress else html_files
+    for html_file in iterator:
         success = process_html_file(
             html_file,
             site_dir,
             md_index,
+            git_data,
+            repo_url,
             site_url=site_url,
             default_image=default_image,
             default_author=default_author,
@@ -146,9 +166,12 @@ def postprocess_site(
             add_css=add_css,
             add_copy_llm=add_copy_llm,
             verbose=verbose,
+            log=log_fn,
         )
         if success:
             processed += 1
+    if progress:
+        progress.close()
 
     print(f"✅ Postprocessing complete: {processed}/{len(html_files)} files processed")
 

{mkdocs_ultralytics_plugin-0.2.0 → mkdocs_ultralytics_plugin-0.2.2}/plugin/processor.py

@@ -27,37 +27,47 @@ COPY_ICON = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d
 CHECK_ICON = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9 16.17L4.83 12l-1.42 1.41L9 19L21 7l-1.41-1.41L9 16.17z"></path></svg>'
 
 
-def get_git_info(file_path: str, add_authors: bool = True, default_author: str | None = None) -> dict[str, Any]:
-    """Retrieve git information including creation/modified dates and optional authors."""
+def get_git_info(
+    file_path: str,
+    add_authors: bool = True,
+    default_author: str | None = None,
+    git_data: dict[str, dict[str, Any]] | None = None,
+    repo_url: str | None = None,
+) -> dict[str, Any]:
+    """Retrieve git information (dates + optional authors) from precomputed git data."""
     file_path = str(Path(file_path).resolve())
     git_info = {
         "creation_date": DEFAULT_CREATION_DATE,
         "last_modified_date": DEFAULT_MODIFIED_DATE,
     }
 
-    try:
-        subprocess.check_output(["git", "rev-parse", "--is-inside-work-tree"], stderr=subprocess.DEVNULL)
-        creation_output = subprocess.check_output(
-            ["git", "log", "--reverse", "--pretty=format:%ai", file_path]
-        ).decode()
-        creation_date = creation_output.split("\n")[0] if creation_output else ""
-        last_modified_date = subprocess.check_output(["git", "log", "-1", "--pretty=format:%ai", file_path]).decode()
-        git_info.update(
-            {
-                "creation_date": creation_date or DEFAULT_CREATION_DATE,
-                "last_modified_date": last_modified_date or DEFAULT_MODIFIED_DATE,
-            }
-        )
+    if not git_data or file_path not in git_data:
+        return git_info
 
-        if add_authors:
-            authors_info = get_github_usernames_from_file(file_path, default_user=default_author)
-            git_info["authors"] = sorted(
-                [(author, info["url"], info["changes"], info["avatar"]) for author, info in authors_info.items()],
-                key=lambda x: x[2],
-                reverse=True,
-            )
-    except (subprocess.CalledProcessError, FileNotFoundError):
-        pass
+    cached = git_data[file_path]
+    git_info.update(
+        {
+            "creation_date": cached.get("creation_date", DEFAULT_CREATION_DATE),
+            "last_modified_date": cached.get("last_modified_date", DEFAULT_MODIFIED_DATE),
+        }
+    )
+
+    if add_authors and cached.get("emails"):
+        git_info["authors"] = sorted(
+            [
+                (
+                    author,
+                    info["url"],
+                    info["changes"],
+                    info["avatar"],
+                )
+                for author, info in get_github_usernames_from_file(
+                    file_path, default_user=default_author, emails=cached["emails"], repo_url=repo_url
+                ).items()
+            ],
+            key=lambda x: x[2],
+            reverse=True,
+        )
 
     return git_info
 
@@ -104,6 +114,90 @@ def insert_content(soup: BeautifulSoup, content_to_insert) -> None:
         md_typeset.append(content_to_insert)
 
 
+def build_git_map(file_paths: list[str] | list[Path]) -> tuple[str | None, dict[str, dict[str, Any]]]:
+    """Build git metadata for provided files using a single git log pass."""
+    git_data: dict[str, dict[str, Any]] = {}
+    repo_url: str | None = None
+
+    if not file_paths:
+        return repo_url, git_data
+
+    try:
+        repo_root = Path(
+            subprocess.check_output(["git", "rev-parse", "--show-toplevel"], stderr=subprocess.DEVNULL).decode().strip()
+        )
+    except subprocess.CalledProcessError:
+        return repo_url, git_data
+
+    try:
+        github_repo_url = subprocess.check_output(
+            ["git", "-C", str(repo_root), "config", "--get", "remote.origin.url"], stderr=subprocess.DEVNULL
+        ).decode("utf-8")
+        github_repo_url = github_repo_url.strip()
+        if github_repo_url.endswith(".git"):
+            github_repo_url = github_repo_url[:-4]
+        if github_repo_url.startswith("git@"):
+            github_repo_url = "https://" + github_repo_url[4:].replace(":", "/")
+        repo_url = github_repo_url or None
+    except subprocess.CalledProcessError:
+        repo_url = None
+
+    rel_paths = []
+    for fp in file_paths:
+        path = Path(fp)
+        if path.exists():
+            try:
+                rel_paths.append(path.resolve().relative_to(repo_root))
+            except ValueError:
+                continue
+    if not rel_paths:
+        return repo_url, git_data
+
+    cmd = [
+        "git",
+        "-C",
+        str(repo_root),
+        "log",
+        "--name-only",
+        "--pretty=format:%ad\t%ae",
+        "--date=format:%Y-%m-%d %H:%M:%S %z",
+        "--",
+        *[str(p) for p in rel_paths],
+    ]
+
+    try:
+        output = subprocess.check_output(cmd, stderr=subprocess.DEVNULL).decode().splitlines()
+    except subprocess.CalledProcessError:
+        return repo_url, git_data
+
+    current_date = None
+    current_email = None
+    for line in output:
+        if not line.strip():
+            continue
+        parts = line.split("\t")
+        if len(parts) == 2:
+            current_date, current_email = parts
+            continue
+
+        if current_date and current_email:
+            abs_path = (repo_root / line.strip()).resolve()
+            key = str(abs_path)
+            entry = git_data.setdefault(
+                key,
+                {
+                    "creation_date": current_date,
+                    "last_modified_date": current_date,
+                    "emails": {},
+                },
+            )
+            entry.setdefault("last_modified_date", current_date)
+            entry["creation_date"] = current_date
+            entry["emails"][current_email] = entry["emails"].get(current_email, 0) + 1
+
+    return repo_url, git_data
+
+
 def get_css() -> str:
     """CSS for git info, share buttons, and copy button."""
     return """
@@ -212,6 +306,8 @@ def process_html(
     page_url: str,
     title: str,
     src_path: str | None = None,
+    git_data: dict[str, dict[str, Any]] | None = None,
+    repo_url: str | None = None,
     default_image: str | None = None,
     default_author: str | None = None,
     keywords: str | None = None,
@@ -245,17 +341,29 @@ def process_html(
         if len(desc) >= 10:
             meta["description"] = desc
 
+    # ---------- IMAGE PICKING (body only, non-AVIF) ----------
     if add_image:
-        if first_image := soup.find("img"):
-            img_src = first_image.get("src", "")
-            if img_src and (
-                img_src.startswith(("http://", "https://", "/")) or not img_src.startswith(("javascript:", "data:"))
-            ):
-                meta["image"] = img_src
-        elif youtube_ids := get_youtube_video_ids(soup):
-            meta["image"] = f"https://img.youtube.com/vi/{youtube_ids[0]}/maxresdefault.jpg"
-        elif default_image:
-            meta["image"] = default_image
+        search_root = soup.find("article", class_="md-content__inner") or soup.body or soup
+
+        image_src: str | None = None
+        for img in search_root.find_all("img", src=True):
+            src = img["src"]
+            lower = src.lower()
+            if not lower or ".avif" in lower:
+                continue
+            if lower.startswith(("javascript:", "data:")):
+                continue
+            image_src = src
+            break
+
+        if not image_src and (youtube_ids := get_youtube_video_ids(soup)):
+            image_src = f"https://img.youtube.com/vi/{youtube_ids[0]}/maxresdefault.jpg"
+        if not image_src and default_image:
+            image_src = default_image
+
+        if image_src:
+            meta["image"] = image_src
+    # ---------------------------------------------------------
 
     # Add meta tags to head
     if not soup.find("meta", attrs={"name": "title"}):
@@ -377,15 +485,17 @@ def process_html(
             """
             soup.body.append(script)
 
-    # Initialize git info with defaults
+    # Initialize git info with defaults and only call git when needed (authors or JSON-LD)
     git_info = {
         "creation_date": DEFAULT_CREATION_DATE,
         "last_modified_date": DEFAULT_MODIFIED_DATE,
     }
+    needs_git = (add_authors or add_json_ld) and src_path
 
-    # Add git information if source path available
-    if src_path:
-        git_info = get_git_info(src_path, add_authors=add_authors, default_author=default_author)
+    if needs_git:
+        git_info = get_git_info(
+            src_path, add_authors=add_authors, default_author=default_author, git_data=git_data, repo_url=repo_url
+        )
 
         # Only render git footer if we have real git history (not placeholder defaults)
         has_real_git_data = (

{mkdocs_ultralytics_plugin-0.2.0 → mkdocs_ultralytics_plugin-0.2.2}/plugin/utils.py

@@ -2,12 +2,10 @@
 
 from __future__ import annotations
 
-import contextlib
 import re
-import subprocess
-from collections import Counter
 from datetime import datetime
 from pathlib import Path
+from typing import Any
 
 import requests
 import yaml  # YAML is used for its readability and consistency with MkDocs ecosystem
@@ -141,8 +139,13 @@ def get_github_username_from_email(
     return None, None
 
 
-def get_github_usernames_from_file(file_path: str, default_user: str | None = None) -> dict[str, dict[str, any]]:
-    """Fetch GitHub usernames associated with a file using Git Log and Git Blame commands.
+def get_github_usernames_from_file(
+    file_path: str,
+    default_user: str | None = None,
+    emails: dict[str, int] | None = None,
+    repo_url: str | None = None,
+) -> dict[str, dict[str, Any]]:
+    """Fetch GitHub usernames associated with a file using provided Git email counts.
 
     Args:
         file_path (str): The path to the file for which GitHub usernames are to be retrieved.
@@ -157,38 +160,13 @@ def get_github_usernames_from_file(file_path: str, default_user: str | None = No
             - 'avatar' (str): The URL of the author's GitHub avatar.
 
     Examples:
-        >>> print(get_github_usernames_from_file('mkdocs.yml'))
-        {'username1': {'email': 'user@example.com', 'url': 'https://github.com/username1', 'changes': 5, 'avatar': '...'}}
+        >>> print(get_github_usernames_from_file('mkdocs.yml', emails={'user@example.com': 2}))
+        {'username1': {'email': 'user@example.com', 'url': 'https://github.com/username1', 'changes': 2, 'avatar': '...'}}
     """
-    # Fetch author emails using 'git log'
-    try:
-        authors_emails_log = (
-            subprocess.check_output(["git", "log", "--pretty=format:%ae", Path(file_path).resolve()])
-            .decode("utf-8")
-            .split("\n")
-        )
-        emails = dict(Counter(authors_emails_log))
-    except subprocess.CalledProcessError:
-        emails = {}  # Git not available or file not in git repo
-
-    # Fetch author emails using 'git blame'
-    with contextlib.suppress(Exception):
-        authors_emails_blame = (
-            subprocess.check_output(
-                ["git", "blame", "--line-porcelain", Path(file_path).resolve()],
-                stderr=subprocess.DEVNULL,
-            )
-            .decode("utf-8")
-            .split("\n")
-        )
-        authors_emails_blame = [line.split(" ")[1] for line in authors_emails_blame if line.startswith("author-mail")]
-        authors_emails_blame = [email.strip("<>") for email in authors_emails_blame]
-        emails_blame = dict(Counter(authors_emails_blame))
-
-        # Merge the two email lists, adding any missing authors from 'git blame' as a 1-commit change
-        for email in emails_blame:
-            if email not in emails:
-                emails[email] = 1  # Only add new authors from 'git blame' with a 1-commit change
+    if emails is None:
+        emails = {}
+    else:
+        emails = dict(emails)  # shallow copy to avoid mutating caller data
 
     # If no git info found but default_user provided, use default_user
     if not emails and default_user:
@@ -202,16 +180,7 @@ def get_github_usernames_from_file(file_path: str, default_user: str | None = No
     else:
         cache = {}
 
-    try:
-        github_repo_url = (
-            subprocess.check_output(["git", "config", "--get", "remote.origin.url"]).decode("utf-8").strip()
-        )
-        if github_repo_url.endswith(".git"):
-            github_repo_url = github_repo_url[:-4]
-        if github_repo_url.startswith("git@"):
-            github_repo_url = "https://" + github_repo_url[4:].replace(":", "/")
-    except subprocess.CalledProcessError:
-        github_repo_url = "https://github.com/ultralytics/ultralytics"  # Fallback URL
+    github_repo_url = repo_url or "https://github.com/ultralytics/ultralytics"
 
     info = {}
     for email, changes in emails.items():