Merge branch 'main' into feat-option-defaults

Author: machow

docs/.gitignore

@@ -14,3 +14,5 @@ _inv
 objects.json
 _sidebar.yml
 _extensions
+
+/.luarc.json

quartodoc/__main__.py

@@ -8,8 +8,9 @@
 from pathlib import Path
 from watchdog.observers import Observer
 from functools import partial
-from watchdog.events import FileSystemEventHandler
+from watchdog.events import PatternMatchingEventHandler
 from quartodoc import Builder, convert_inventory
+from pydantic import BaseModel
 
 def get_package_path(package_name):
     """
@@ -21,24 +22,83 @@ def get_package_path(package_name):
     except ModuleNotFoundError:
         raise ModuleNotFoundError(f"Package {package_name} not found.  Please install it in your environment.")
 
-class FileChangeHandler(FileSystemEventHandler):
+
+class FileInfo(BaseModel):
+    size: int
+    mtime: float
+    name: str= ""
+
+class QuartoDocFileChangeHandler(PatternMatchingEventHandler):
     """
     A handler for file changes.
     """
+
+    # Ignore patterns for the file watcher that are not relevant to the docs
+    py_ignore_patterns = [
+        '*/__pycache__/*',  # These are the compiled python code files which are automatically generated by Python
+        '*/.ipynb_checkpoints/*',  # This directory is created by Jupyter Notebook for auto-saving notebooks
+        '*/.vscode/*',  # If you're using Visual Studio Code, it creates this directory to store settings specific to that project.
+        '*/.idea/*',  # Similar to .vscode/, but for JetBrains IDEs like PyCharm.
+        '*/.git/*',  # i This directory is created by Git. It's not relevant to the docs.
+        '*/venv/*', '*/env/*',  '*/.env/*',  # Common names for directories containing a Python virtual environment.
+        '*/.pytest_cache/*',  # This directory is created when you run Pytest.
+        '*/.eggs/*', '*/dist/*', '*/build/*', '*/*.egg-info/*', # These are typically created when building Python packages with setuptools.
+        '*.pyo',  # These are optimized .pyc files, created when Python is run with the -O flag.
+        '*.pyd',  # This is the equivalent of a .pyc file, but for C extensions on Windows.
+        '*/.mypy_cache/*', # This directory is created when you run mypy.
+    ]
+
     def __init__(self, callback):
+        super().__init__(ignore_patterns=self.py_ignore_patterns, ignore_directories=True)
         self.callback = callback
+        self.old_file_info = FileInfo(size=-1, mtime=-1, name="")
+
+
+    def get_file_info(self, path:str) -> FileInfo:
+        """
+        Get the file size and modification time.
+        """
+        return FileInfo(size=os.stat(path).st_size, 
+                        mtime=os.stat(path).st_mtime, 
+                        name=path)
 
+    def is_diff(self, old:FileInfo, new:FileInfo) -> bool:
+        """
+        Check if a file has changed. Prevents duplicate events from being triggered.
+        """
+        same_nm = old.name == new.name
+        diff_sz = old.size != new.size
+        diff_tm = (new.mtime - old.mtime) # wait 1/4 second before triggering
+
+        if diff_tm < .25: # if consequetive events are less than 1/4th of a second apart, ignore
+            return False
+        elif same_nm:
+            if diff_sz or diff_tm >= 0.25:
+                return True
+            else:
+                return False
+        else:
+            return True     
+    
+    def callback_if_diff(self, event):
+        """
+        Call the callback if the file has changed.
+        """
+        new_file_info = self.get_file_info(event.src_path)
+        if self.is_diff(self.old_file_info, new_file_info):
+            self.print_event(event)
+            self.callback()
+        self.old_file_info = new_file_info
+
     @classmethod
     def print_event(cls, event):
         print(f'Rebuilding docs.  Detected: {event.event_type} path : {event.src_path}')
 
     def on_modified(self, event):
-        self.print_event(event)
-        self.callback()
+        self.callback_if_diff(event)
 
     def on_created(self, event):
-        self.print_event(event)
-        self.callback()
+        self.callback_if_diff(event)
 
 def _enable_logs():
     import logging
@@ -71,9 +131,6 @@ def cli():
     pass
 
 
-
-
-
 @click.command()
 @click.option("--config", default="_quarto.yml", help="Change the path to the configuration file.  The default is `./_quarto.yml`")
 @click.option("--filter", nargs=1, default="*", help="Specify the filter to select specific files. The default is '*' which selects all files.")
@@ -84,6 +141,11 @@ def build(config, filter, dry_run, watch, verbose):
     """
     Generate API docs based on the given configuration file  (`./_quarto.yml` by default).
     """
+    cfg_path = f"{os.getcwd()}/{config}"
+    if not Path(cfg_path).exists():
+        raise FileNotFoundError(
+            f"Configuration file {cfg_path} not found.  Please create one."
+        )
     if verbose:
         _enable_logs()
 
@@ -97,16 +159,20 @@ def build(config, filter, dry_run, watch, verbose):
             if watch:
                 pkg_path = get_package_path(builder.package)
                 print(f"Watching {pkg_path} for changes...")
-                event_handler = FileChangeHandler(callback=doc_build)
                 observer = Observer()
+                observer._event_queue.maxsize = 1 # the default is 0 which is infinite, and there isn't a way to set this in the constructor
+                event_handler = QuartoDocFileChangeHandler(callback=doc_build)
                 observer.schedule(event_handler, pkg_path, recursive=True)
+                observer.schedule(event_handler, cfg_path, recursive=True)
                 observer.start()
                 try:
                     while True:
                         time.sleep(1)
                 except KeyboardInterrupt:
+                    pass
+                finally:
                     observer.stop()
-                observer.join()
+                    observer.join()
             else:   
                 doc_build()