Merge branch 'main' into feat-automodule

Author: machow

Makefile

@@ -19,8 +19,9 @@ $(EXAMPLE_INTERLINKS)/test.md: $(EXAMPLE_INTERLINKS)/test.qmd _extensions/interl
 
 examples/%/_site: examples/%/_quarto.yml
 	cd examples/$* \
-		&& quarto add --no-prompt ../..
-	cd examples/$* && quartodoc build _quarto.yml --verbose
+		&& quarto add --no-prompt ../.. \
+		&& quarto add --no-prompt quarto-ext/shinylive
+	cd examples/$* && quartodoc build --config _quarto.yml --verbose
 	cd examples/$* && quartodoc interlinks
 	quarto render $(dir $<)
 

docs/get-started/basic-building.qmd

@@ -9,27 +9,46 @@ jupyter:
 
 **tl;dr**: Once you've configured quartodoc in your `_quarto.yml` file, use the following commands to build and preview a documentation site.
 
+## Create documentation files with `quartodoc build`
+
+Automatically generate `.qmd` files with reference api documentation.  This is written by default to the reference/ folder in your quarto project.
+
 ```bash
-# Create the documentation files. These are written 
-# by default to the reference/ folder in your docs.
-quartodoc build --verbose
+quartodoc build
+```
 
-# Create optional inventory files, which allow you to
-# link to API doc pages within and across documentation
-# sites. These are put in the _inv folder in your docs.
-quartodoc interlinks
+If you are iterating on your docstrings while previewing your site with `quarto preview`, you will likely want to rebuild the doc pages automatically when docstrings change.  The `--watch` flag does exactly this.
 
-# Preview the documentation site.
-# Use quarto render to generate the final site.
-quarto preview
+```bash
+quartodoc build --watch
 ```
 
-## Rebuilding doc pages
+For more information on the `quartodoc build` command, use `--help` in the terminal like so:
 
-While using `quarto preview`, you can preview updates to your docstrings by regenerating their documentation pages:
+```bash
+quartodoc build --help
+```
+
+```{python}
+#|echo: false
+!quartodoc build --help
+```
 
+
+## Create inventory files with `quartodoc interlinks`
+
+Inventory files facilitate linking to API doc pages within and across `quartodoc` sites.  This is optional.
+  
 ```bash
-quartodoc build --verbose
+quartodoc interlinks
+```
+
+## Preview the site with `quarto preview`
+
+Use `quarto` to preview the site:
+
+```bash
+quarto preview
 ```
 
 ## Speeding up preview

docs/get-started/overview.qmd

@@ -85,20 +85,18 @@ quarto preview
 
 ## Rebuilding site
 
-As mentioned in the previous section, you can preview your quartodoc site using these commands:
+You can preview your `quartodoc` site using the following commands:
+
+First, watch for changes to the library you are documenting so that your docs will automatically re-generate:
 
 ```bash
-quartodoc build
-quarto preview
+quartodoc build --watch
 ```
 
-In order to rebuild your API documentation pages during a quarto preview, re-run
-the quartodoc build command:
+Second, preview your site:
 
 ```bash
-# with quarto preview running, you only need to re-run quartodoc build,
-# which will re-create the pages of your API documentation.
-quartodoc build
+quarto preview
 ```
 
 ## Looking up objects

quartodoc/__main__.py

@@ -1,13 +1,44 @@
 import click
 import contextlib
 import os
+import time
 import sphobjinv as soi
 import yaml
-
+import importlib
 from pathlib import Path
-
+from watchdog.observers import Observer
+from functools import partial
+from watchdog.events import FileSystemEventHandler
 from quartodoc import Builder, convert_inventory
 
+def get_package_path(package_name):
+    """
+    Get the path to a package installed in the current environment.
+    """
+    try:
+        lib = importlib.import_module(package_name)
+        return lib.__path__[0]
+    except ModuleNotFoundError:
+        raise ModuleNotFoundError(f"Package {package_name} not found.  Please install it in your environment.")
+
+class FileChangeHandler(FileSystemEventHandler):
+    """
+    A handler for file changes.
+    """
+    def __init__(self, callback):
+        self.callback = callback
+    
+    @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()
+
+    def on_created(self, event):
+        self.print_event(event)
+        self.callback()
 
 def _enable_logs():
     import logging
@@ -40,24 +71,44 @@ def cli():
     pass
 
 
+
+
+
 @click.command()
-@click.argument("config", default="_quarto.yml")
-@click.option("--filter", nargs=1, default="*")
-@click.option("--dry-run", is_flag=True, default=False)
-@click.option("--verbose", is_flag=True, default=False)
-def build(config, filter, dry_run, verbose):
+@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.")
+@click.option("--dry-run", is_flag=True, default=False, help="If set, prevents new documents from being generated.")
+@click.option("--watch", is_flag=True, default=False, help="If set, the command will keep running and watch for changes in the package directory.")
+@click.option("--verbose", is_flag=True, default=False, help="Enable verbose logging.")
+def build(config, filter, dry_run, watch, verbose):
+    """
+    Generate API docs based on the given configuration file  (`./_quarto.yml` by default).
+    """
     if verbose:
         _enable_logs()
 
     builder = Builder.from_quarto_config(config)
+    doc_build = partial(builder.build, filter=filter)
 
     if dry_run:
-        # click.echo(builder.render_index())
         pass
     else:
         with chdir(Path(config).parent):
-            builder.build(filter=filter)
-
+            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.schedule(event_handler, pkg_path, recursive=True)
+                observer.start()
+                try:
+                    while True:
+                        time.sleep(1)
+                except KeyboardInterrupt:
+                    observer.stop()
+                observer.join()
+            else:   
+                doc_build()
 
 @click.command()
 @click.argument("config", default="_quarto.yml")

setup.cfg

@@ -32,7 +32,7 @@ install_requires =
     pydantic<2.0
     pyyaml
     typing-extensions>=4.4.0
-
+    watchdog>=3.0.0
 
 [options.extras_require]
 dev =
@@ -46,10 +46,6 @@ console_scripts =
     quartodoc = quartodoc.__main__:cli
 
 
-[project.scripts]
-quartodoc = "quartodoc.cli:main"
-
-
 [bdist_wheel]
 universal = 1