From dcf1127e927534a8d05eda290b1f57d580845771 Mon Sep 17 00:00:00 2001
From: Eric Pinzur <epinzur@gmail.com>
Date: Sun, 8 Oct 2023 07:41:06 -0500
Subject: [PATCH] updated readme

---
 python/README.md  | 29 +++++++++++++++++++++++++++++
 python/noxfile.py | 27 ++++++++++-----------------
 2 files changed, 39 insertions(+), 17 deletions(-)

diff --git a/python/README.md b/python/README.md
index 2ea1da6cb..29c04bf09 100644
--- a/python/README.md
+++ b/python/README.md
@@ -33,3 +33,32 @@ Alternatively, install nox and run the tests inside an isolated environment:
 ```shell
 nox
 ```
+
+## Previewing Docs
+
+* Install `quarto-cli` on your machine. Also consider installing an IDE extension.
+
+  See: https://quarto.org/docs/get-started/
+
+* Generate reference docs
+
+  ```shell
+  nox -s gen-docs
+  ```
+
+  You should re-run this after making any updates to the `pysrc` docstrings.
+  If _Preview Docs_ is running in another shell, the system should auto-refresh with your changes.
+
+* Preview docs (with auto-refresh on edit)
+
+  ```shell
+  nox -s docs
+  ```
+
+* Cleanup generated and cached docs
+
+  ```shell
+  nox -s docs-clean
+  ```
+
+  Try this if you see something unexpected (especially after deleting or renaming).
diff --git a/python/noxfile.py b/python/noxfile.py
index dcfcd3df9..34010f305 100644
--- a/python/noxfile.py
+++ b/python/noxfile.py
@@ -114,24 +114,22 @@ def xdoctest(session: nox.Session) -> None:
     install(session, groups=["test"])
     session.run("python", "-m", "xdoctest", *args)
 
+@nox.session(name="docs-clean", python=python_versions[0])
+def docs_clean(session: nox.Session) -> None:
+    """Clean up generated and cached docs"""
+
+    for item in [".quarto", "reference", "_inv", "objects.json"]:
+        p = Path("docs", item)
+        if p.exists() and p.is_dir():
+            shutil.rmtree(dir)
+        elif p.exists() and p.is_file():
+            p.unlink()
 
 @nox.session(name="docs-gen", python=python_versions[0])
 def docs_gen(session: nox.Session) -> None:
     """Generate API reference docs"""
     install(session, groups=["docs"])
 
-    reference_dir = Path("docs", "reference")
-    if reference_dir.exists():
-        shutil.rmtree(reference_dir)
-
-    interlinks_dir = Path("docs", "_inv")
-    if interlinks_dir.exists():
-        shutil.rmtree(interlinks_dir)
-
-    objects_file = Path("docs", "objects.json")
-    if objects_file.exists():
-        objects_file.unlink()
-
     with session.chdir("docs"):
         session.run("python", "_scripts/gen_reference.py")
         session.run("python", "-m", "quartodoc", "interlinks")
@@ -140,13 +138,8 @@ def docs_gen(session: nox.Session) -> None:
 @nox.session(python=python_versions[0])
 def docs(session: nox.Session) -> None:
     """Build and serve the documentation with live reloading on file changes."""
-
     install(session, groups=["docs"])
 
-    build_dir = Path("docs", ".quarto", "_site")
-    if build_dir.exists():
-        shutil.rmtree(build_dir)
-
     with session.chdir("docs"):
         session.run("quarto", "preview", external=True)