Graphviz static rendering and docs

.readthedocs.yml

@@ -10,50 +10,54 @@ build:
   tools:
     python: "3.12"
   apt_packages:
+    # System dependencies - now works because we use jobs instead of commands
     # More closely mirror https://github.com/sphinx-doc/sphinx-docker-images
     - graphviz
+    - graphviz-dev  # Headers for pygraphviz compilation
     - imagemagick
     - make
     - pandoc
     - texlive-latex-base
     - texlive-latex-recommended
     - texlive-latex-extra
     - texlive-fonts-recommended
-  commands:
+  jobs:
+    post_install:
+      # Copy content into docs/source after pip install
+      - cp -r demos docs/source/demos
+      - cp README.md docs/source/README.md
+      - cp ARCHITECTURE.md docs/source/ARCHITECTURE.md
+      - cp CONTRIBUTING.md docs/source/CONTRIBUTING.md
+      - cp DEVELOP.md docs/source/DEVELOP.md
+    build:
+      html:
+        - sphinx-build -b html -d docs/doctrees docs/source $READTHEDOCS_OUTPUT/html/
+      epub:
+        - sphinx-build -b epub -d docs/doctrees docs/source docs/_build/epub
+        - mkdir -p $READTHEDOCS_OUTPUT/epub
+        - cp docs/_build/epub/PyGraphistry.epub $READTHEDOCS_OUTPUT/epub/PyGraphistry.epub
+      pdf:
+        # Build LaTeX then run pdflatex 3 times to resolve cross-references
+        - sphinx-build -b latex -d docs/doctrees docs/source docs/_build/latexpdf
+        - cd docs/_build/latexpdf && pdflatex -file-line-error -interaction=nonstopmode PyGraphistry.tex
+        - cd docs/_build/latexpdf && pdflatex -file-line-error -interaction=nonstopmode PyGraphistry.tex
+        - cd docs/_build/latexpdf && pdflatex -file-line-error -interaction=nonstopmode PyGraphistry.tex
+        - mkdir -p $READTHEDOCS_OUTPUT/pdf
+        - cp docs/_build/latexpdf/PyGraphistry.pdf $READTHEDOCS_OUTPUT/pdf/PyGraphistry.pdf
 
-    # setup
-    - pip install ".[docs]"
-    - cp -r demos docs/source/demos
-    - cp README.md docs/source/README.md
-    - cp ARCHITECTURE.md docs/source/ARCHITECTURE.md
-    - cp CONTRIBUTING.md docs/source/CONTRIBUTING.md
-    - cp DEVELOP.md docs/source/DEVELOP.md
-
-    # build html
-    - sphinx-build -b html -d docs/doctrees docs/source $READTHEDOCS_OUTPUT/html/
-
-    # build epub
-    - sphinx-build -b epub -d docs/doctrees docs/source docs/_build/latexpdf
-    - mkdir -p $READTHEDOCS_OUTPUT/epub
-    - cp docs/_build/latexpdf/PyGraphistry.epub $READTHEDOCS_OUTPUT/epub/PyGraphistry.epub
-
-    # build pdf - run pdflatex 3 times to resolve cross-references
-    - sphinx-build -b latex -d docs/doctrees docs/source docs/_build/latexpdf
-    - cd docs/_build/latexpdf && pdflatex -file-line-error -interaction=nonstopmode PyGraphistry.tex
-    - cd docs/_build/latexpdf && pdflatex -file-line-error -interaction=nonstopmode PyGraphistry.tex
-    - cd docs/_build/latexpdf && pdflatex -file-line-error -interaction=nonstopmode PyGraphistry.tex
-    - mkdir -p $READTHEDOCS_OUTPUT/pdf
-    - cp docs/_build/latexpdf/PyGraphistry.pdf $READTHEDOCS_OUTPUT/pdf/PyGraphistry.pdf
-
-#for nav links?
 formats:
   - pdf
   - epub
   - htmlzip
 
+# sphinx key triggers RTD's Sphinx support for environment/install steps
+sphinx:
+  configuration: docs/source/conf.py
+
 python:
   install:
     - method: pip
       path: .
       extra_requirements:
         - docs
+        - pygraphviz  # For plot_static() notebook execution

CHANGELOG.md

@@ -8,23 +8,22 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 ## [Development]
 <!-- Do Not Erase This Section - Used for tracking unreleased changes -->
 
+### Added
+- **Layouts / Graphviz**: `plot_static` now supports engines `graphviz-svg/png`, `graphviz-dot`, and `mermaid-code`, honoring `reuse_layout` for bound positions and optional file outputs; Graphviz render accepts passthrough args/positions for consistent layouts.
+
 ### Fixed
 - **GFQL:** `Chain` now validates on construction (matching docs) and rejects invalid hops immediately; pass `validate=False` to defer validation when assembling advanced flows (fixes #860).
 - **GFQL / eq:** `eq()` now accepts strings in addition to numeric/temporal values (use `isna()`/`notna()` for nulls); added coverage across validator, schema validation, JSON, and GFQL runtime (fixes #862).
 
 ### Docs
-- **GFQL validation:** Clarified `Chain` constructor validation defaults, `validate=False` defer option, validation phases, and guidance for large/nested ASTs to reduce redundant validation (issue #860).
+- **Graphviz**: Enabled `sphinx.ext.graphviz`, allowed rstcheck `graphviz` directive, and added static Graphviz + DOT/Mermaid examples across 10min, visualization 10min, GFQL spec (MyST), and the Graphviz demo notebook (uses `plot_static` inline). Docs Docker image now installs graphviz/pygraphviz/gcc and `docs/ci.sh` builds only the sphinx service.
+- **RTD**: Fixed graphviz on Read the Docs by switching from `build.commands` to `build.jobs` (RTD's `apt_packages` is incompatible with `commands`). Docs now fail fast with clear error if `dot` is missing.
 
-## [0.46.0 - 2025-12-01]
+### Tests
+- **Graphviz**: Added coverage for `plot_static` DOT/Mermaid engines and position reuse.
 
-### Added
-- **Plot: Geographic visualization support with Kepler.gl integration** (#799)
-  * New bindings: `point_longitude` and `point_latitude` for specifying geographic coordinates
-  * Kepler.gl encoding methods: `encode_kepler()`, `encode_kepler_dataset()`, `encode_kepler_layer()`, `encode_kepler_options()`, `encode_kepler_config()`
-  * Configuration classes: `KeplerEncoding`, `KeplerDataset`, `KeplerLayer`, `KeplerOptions`, `KeplerConfig`
-  * `mercator_layout()` - Convert lat/lon to Mercator projection with GPU/CPU support
-  * Comprehensive user guide and API documentation
-  * Added 55 tests in `test_kepler.py` and 6 tests in `test_layout.py`
+### Infra
+- **AI / Planning**: Plan template now forbids working directly on `main`/`master`.
 
 ## [0.45.10 - 2025-11-19]
 

ai/prompts/PLAN.md

@@ -78,7 +78,7 @@
 **Branch Strategy**: [How branches will be organized]
 **PR/Branch Stack**: [If stacked PRs, list order: PR#123 (branch-1) → PR#124 (branch-2)]
 **Merge Order**: [Order to merge if multiple PRs]
-**Note**: Track branch/PR per phase as they may change (e.g., rebase flows)
+**Note**: Track branch/PR per phase as they may change (e.g., rebase flows). Do **not** work on `main`/`master`; create/use a branch that follows this repo’s naming convention and fits the task (e.g., `feat/...`, `fix/...`, or repo-specific dev/staging patterns).
 
 ## Status Legend
 - 📝 **TODO**: Not started
@@ -238,4 +238,4 @@ Every ~20 completed phases:
 
 ---
 *Plan created: [date]*
-*Last updated: [date]*
+*Last updated: [date]*