add note for auto-generated documentation

docs/editors/neovim.md

@@ -2,6 +2,12 @@
 title: Neovim
 ---
 
+<!--
+THIS FILE IS AUTO-GENERATED
+DO NOT EDIT THIS FILE DIRECTLY
+Generated via docs/processor.py from editors/nvim/README.md
+-->
+
 # djls.nvim
 
 A Neovim plugin for the Django Language Server.

docs/index.md

@@ -2,6 +2,12 @@
 title: Home
 ---
 
+<!--
+THIS FILE IS AUTO-GENERATED
+DO NOT EDIT THIS FILE DIRECTLY
+Generated via docs/processor.py from README.md
+-->
+
 # django-language-server
 
 A language server for the Django web framework.

docs/processor.py

@@ -14,6 +14,7 @@ from __future__ import annotations
 import logging
 import re
 from dataclasses import dataclass
+from dataclasses import field
 from difflib import Differ
 from functools import reduce
 from itertools import islice
@@ -37,8 +38,6 @@ logging.basicConfig(
 )
 logger = logging.getLogger(__name__)
 
-ProcessingFunc = Callable[[str], str]
-
 
 def compose(*functions: ProcessingFunc) -> ProcessingFunc:
     """Compose multiple processing functions into a single function."""
@@ -270,52 +269,65 @@ def preview_changes(original: str, processed: str) -> None:
         print_change_group(group)
 
 
-def process_file(
+@dataclass
-    input: str = "README.md",
+class File:
-    output: str = "docs/index.md",
+    """A file to be processed."""
-    processors: list[ProcessingFunc] | None = None,
-    preview: bool = True,
-    description: str | None = None,
-) -> bool:
-    """
-    Process a file with given processing functions.
 
-    Args:
+    input_path: Path | str
-        input: Path to the input file
+    output_path: Path | str
-        output: Path where the processed file will be saved
+    repo_url: str = "https://github.com/joshuadavidthomas/django-language-server"
-        processors: List of processing functions to apply
+    content: str = ""
-        preview: Whether to show a preview of changes
+    processors: list[ProcessingFunc] = field(default_factory=list)
-        description: Optional description for status message
 
-    Returns:
+    def __post_init__(self):
-        bool: True if processing was successful, False otherwise
+        self.input_path = Path(self.input_path)
-    """
+        self.output_path = Path(self.output_path)
-    status_msg = f"[bold green]Processing {description or input}..."
-    with console.status(status_msg) as status:
-        input_path = Path(input)
-        output_path = Path(output)
 
-        content = read_file(input_path)
+    def process(self, preview: bool = True) -> bool:
+        """Process the file with given processing functions."""
+        with console.status(
+            f"[bold green]Processing {self.input_path} → {self.output_path}..."
+        ) as status:
+            content = read_file(self.input_path)
             if content is None:
                 return False
 
+            self.content = content
             original_content = content
 
             try:
-            for proc in track(processors, description="Applying processors"):
+                for proc in track(self.processors, description="Applying processors"):
                     status.update(f"[bold green]Running {proc.__name__}...")
-                content = proc(content)
+                    content = proc(content, self)
 
                 if preview:
                     preview_changes(original_content, content)
 
-            return write_file(output_path, content)
+                return write_file(self.output_path, content)
 
             except Exception as e:
                 console.print(f"[red]Error during processing:[/red] {e}")
                 return False
 
 
+ProcessingFunc = Callable[[str, File], str]
+
+
+def add_generated_warning(content: str, file: File) -> str:
+    """Add a warning comment indicating the file is auto-generated."""
+    script_path = Path(__file__).relative_to(Path(__file__).parent.parent)
+    warning = [
+        "<!--",
+        "THIS FILE IS AUTO-GENERATED",
+        "DO NOT EDIT THIS FILE DIRECTLY",
+        f"Generated via {script_path} from {file.input_path}",
+        "-->",
+        "",
+        "",
+    ]
+    return "\n".join(warning) + content
+
+
 def add_frontmatter(
     metadata: dict[str, str | int | float | bool | list | None],
 ) -> ProcessingFunc:
@@ -345,7 +357,7 @@ def add_frontmatter(
             Content here
     """
 
-    def processor(content: str) -> str:
+    def processor(content: str, _file: File) -> str:
         # Remove existing frontmatter if present
         content_without_frontmatter = re.sub(
             r"^---\n.*?\n---\n", "", content, flags=re.DOTALL
@@ -371,7 +383,7 @@ def add_frontmatter(
     return processor
 
 
-def convert_admonitions(content: str) -> str:
+def convert_admonitions(content: str, _file: File) -> str:
     """
     Convert GitHub-style admonitions to Material for MkDocs-style admonitions.
 
@@ -431,29 +443,9 @@ def convert_admonitions(content: str) -> str:
     return re.sub(pattern, process_match, content)
 
 
-def convert_repo_links(repo_url: str) -> ProcessingFunc:
+def convert_repo_links(content: str, file: File) -> str:
-    """
+    """Convert relative repository links to absolute URLs."""
-    Convert relative repository links to absolute URLs.
 
-    Args:
-        repo_url: The base repository URL (e.g., 'https://github.com/username/repo')
-
-    Returns:
-        A processor function that converts relative links to absolute URLs
-
-    Example:
-        Input:
-            See the [`LICENSE`](LICENSE) file for more information.
-            Check the [Neovim](/docs/editors/neovim.md) guide.
-            Open an [issue](../../issues/new) to report bugs.
-
-        Output:
-            See the [`LICENSE`](https://github.com/username/repo/blob/main/LICENSE) file for more information.
-            Check the [Neovim](editors/neovim.md) guide.
-            Open an [issue](https://github.com/username/repo/issues/new) to report bugs.
-    """
-
-    def processor(content: str) -> str:
     def replace_link(match: re.Match[str]) -> str:
         text = match.group(1)
         path = match.group(2)
@@ -477,7 +469,7 @@ def convert_repo_links(repo_url: str) -> ProcessingFunc:
             # Special handling for GitHub-specific paths
             if "issues/" in path or "pulls/" in path:
                 clean_path = path.replace("../", "").replace("./", "")
-                    return f"[{text}]({repo_url}/{clean_path})"
+                return f"[{text}]({file.repo_url}/{clean_path})"
 
         # Handle root-relative paths
         if path.startswith("/"):
@@ -487,50 +479,47 @@ def convert_repo_links(repo_url: str) -> ProcessingFunc:
         path = path.removeprefix("./")
 
         # Construct the full URL for repository files
-            full_url = f"{repo_url.rstrip('/')}/blob/main/{path}"
+        full_url = f"{file.repo_url.rstrip('/')}/blob/main/{path}"
         return f"[{text}]({full_url})"
 
     # Match markdown links: [text](url)
     pattern = r"\[((?:[^][]|\[[^]]*\])*)\]\(([^)]+)\)"
     return re.sub(pattern, replace_link, content)
 
-    processor.__name__ = "convert_repo_links"
-    return processor
-
 
 def main():
     """Process documentation files."""
     console.print("[bold blue]Documentation Processor[/bold blue]")
 
+    # Common processors
     common_processors = [
+        add_generated_warning,
         convert_admonitions,
-        convert_repo_links(
+        convert_repo_links,
-            "https://github.com/joshuadavidthomas/django-language-server"
-        ),
     ]
 
-    readme_success = process_file(
+    readme = File(
-        input="README.md",
+        input_path="README.md",
-        output="docs/index.md",
+        output_path="docs/index.md",
         processors=[
-            add_frontmatter({"title": "Home"}),
             *common_processors,
+            add_frontmatter({"title": "Home"}),
         ],
-        preview=True,
-        description="README.md → docs/index.md",
     )
 
-    nvim_success = process_file(
+    nvim = File(
-        input="editors/nvim/README.md",
+        input_path="editors/nvim/README.md",
-        output="docs/editors/neovim.md",
+        output_path="docs/editors/neovim.md",
         processors=[
-            add_frontmatter({"title": "Neovim"}),
             *common_processors,
+            add_frontmatter({"title": "Neovim"}),
         ],
-        preview=True,
-        description="Neovim docs → docs/editors/neovim.md",
     )
 
+    # Process files
+    readme_success = readme.process(preview=True)
+    nvim_success = nvim.process(preview=True)
+
     if readme_success and nvim_success:
         console.print("\n[green]✨ All files processed successfully![/green]")
     else: