Merge branch 'main' into feat-subtitles

Author: machow

.github/workflows/ci.yml

@@ -9,16 +9,8 @@ on:
     types: [published]
 
 jobs:
-  run-if:
-    name: "Run If"
-    runs-on: ubuntu-latest
-    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.fork == false
-    steps:
-      - run: |
-          echo "Running CI"
   test:
     name: "Test"
-    needs: ["run-if"]
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false

.pre-commit-config.yaml

@@ -1,4 +1,4 @@
-exclude: ".*\\.(csv)|(md)|(json)"
+exclude: ".*\\.(csv)|(md)|(json)|(ambr)"
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v2.4.0

Makefile

@@ -21,7 +21,7 @@ examples/%/_site: examples/%/_quarto.yml
 	cd examples/$* \
 		&& quarto add --no-prompt ../.. \
 		&& quarto add --no-prompt quarto-ext/shinylive
-	cd examples/$* && quartodoc build _quarto.yml --verbose
+	cd examples/$* && quartodoc build --config _quarto.yml --verbose
 	cd examples/$* && quartodoc interlinks
 	quarto render $(dir $<)
 
@@ -30,7 +30,7 @@ docs/examples/%: examples/%/_site
 	rm -rf docs/examples/$*
 	cp -rv $< $@
 
-docs-build-examples: docs/examples/single-page docs/examples/pkgdown
+docs-build-examples: docs/examples/single-page docs/examples/pkgdown docs/examples/auto-package
 
 docs-build: docs-build-examples
 	cd docs && quarto add --no-prompt ..

docs/_quarto.yml

@@ -4,6 +4,7 @@ project:
   resources:
     - examples/single-page
     - examples/pkgdown
+    - examples/auto-package
 
 metadata-files:
   - api/_sidebar.yml

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.
 
+## `quartodoc build`: Create doc files
+
+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
+```
 
+
+## `quartodoc interlinks`: Create inventory files
+
+Inventory files facilitate linking to API doc pages within and across `quartodoc` sites.  This is optional.
+  
 ```bash
-quartodoc build --verbose
+quartodoc interlinks
+```
+
+## `quarto preview`: Preview the site
+
+Use `quarto` to preview the site:
+
+```bash
+quarto preview
 ```
 
 ## Speeding up preview

docs/get-started/docstring-examples.qmd

@@ -48,6 +48,13 @@ Below is an example including each.
     ```
 ```
 
+Note that different syntaxes are handled differently:
+
+* doctest and markdown syntax: rendered without executing.
+* quarto syntax: executed by quarto when you run commands like `quarto render`.
+
+See the quarto documentation on [code blocks](https://quarto.org/docs/computations/python.html#code-blocks) for more detail.
+
 
 ## Examples, etc..: the "s" matters
 

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

examples/auto-package/_quarto.yml

@@ -0,0 +1,25 @@
+project:
+  type: website
+  resources:
+    - objects.json
+
+website:
+  title: pkgdown example
+  navbar:
+    left:
+      - href: https://machow.github.io/quartodoc/
+        text: quartodoc home
+      - file: reference/index.qmd
+        text: "Reference"
+    right:
+      - icon: github
+        href: https://github.com/machow/quartodoc/tree/main/examples/pkgdown
+
+format:
+  html:
+    toc: true
+
+quartodoc:
+  style: pkgdown
+  dir: reference
+  package: quartodoc

quartodoc/__init__.py

@@ -1,15 +1,26 @@
+"""quartodoc is a package for building delightful python API documentation.
+"""
+
 # flake8: noqa
 
-from .autosummary import (
-    get_function,
-    get_object,
-    Builder,
-    BuilderPkgdown,
-    BuilderSinglePage,
-)
+from .autosummary import get_function, get_object, Builder
 from .renderers import MdRenderer
 from .inventory import convert_inventory, create_inventory
 from .ast import preview
 from .builder.blueprint import blueprint
 from .builder.collect import collect
 from .layout import Auto
+
+__all__ = (
+    "Auto",
+    "blueprint",
+    "collect",
+    "convert_inventory",
+    "create_inventory",
+    "get_object",
+    "preview",
+    "Builder",
+    "BuilderPkgdown",
+    "BuilderSinglePage",
+    "MdRenderer",
+)

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")