Skip to content

Graphviz static rendering and docs #859

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
lmeyerov wants to merge 44 commits into
base: master
Choose a base branch
from
Open

Graphviz static rendering and docs #859

lmeyerov wants to merge 44 commits into from

Conversation

@lmeyerov
Copy link
Contributor

@lmeyerov lmeyerov commented Dec 1, 2025

Summary

  • add plot_static engines for graphviz svg/png, graphviz-dot, and mermaid-code with position reuse support
  • enable sphinx graphviz directive, refresh docs/notebook examples, and build docs image with graphviz/pygraphviz
  • expand graphviz tests for new engines and doc snippets (rst/myst)

Testing

  • PYTHONPATH=. uv run --python /usr/bin/python3 --with numpy --with palettable --with pandas --with pyarrow --with requests --with squarify --with typing-extensions --with packaging --with setuptools --with pygraphviz --with pytest python -m pytest graphistry/tests/plugins/test_graphviz.py -q
  • DOCS_FORMAT=html VALIDATE_NOTEBOOK_EXECUTION=0 ./docs/ci.sh
  • ./docs/validate-docs.sh docs/source/10min.rst docs/source/visualization/10min.rst docs/source/api/plugins/compute/graphviz.rst docs/source/gfql/spec/index.md

@lmeyerov lmeyerov force-pushed the feat/graphviz-docs-rendering branch 3 times, most recently from be41870 to 3c70241 Compare December 4, 2025 07:46
lmeyerov added a commit that referenced this pull request Dec 4, 2025
@lmeyerov @claude
docs(plan): add PR split strategy for safe work preservation
df9e1a0 
Phase 4 documents how to split PR #859 into:
- Base PR: infrastructure + minimal proof-of-work (1 RST, 1 MyST, 1 notebook)
- Stacked PR: rich graphviz examples across all docs

Includes safe workflow with backup tag before trimming.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
lmeyerov added 26 commits December 4, 2025 19:12
@lmeyerov
chore(plan): disallow main or master work
e6c5c1f
@lmeyerov
feat(graphviz): add plot_static and render args with tests
0fbd280
@lmeyerov
ci(docs): build sphinx image with graphviz
fdbd5a1
@lmeyerov
docs(graphviz): enable sphinx directive and embed static examples
ff8b490
@lmeyerov
feat(graphviz): add dot/mermaid engines to plot_static
36c8f08
@lmeyerov
docs(graphviz): add dot/mermaid examples across rst/md
130c71e
@lmeyerov
chore(changelog): note graphviz static rendering work
b5dcd9c
@lmeyerov
docs(graphviz): add small graphviz diagrams to overview/quick/ecosyst…
28907cb 
…em/layout
@lmeyerov
fix(docs): guard mermaid and tidy docstrings for pdf build
eafe3ef
@lmeyerov
ci(docs): allow latexpdf DOCS_FORMAT
8e38f1c
@lmeyerov
Revert "ci(docs): allow latexpdf DOCS_FORMAT"
2a694f4 
This reverts commit 86a449c.
@lmeyerov
fix(docs): clean ASTLet and spanner docstrings for RTD
65939b3
@lmeyerov
fix(docs): normalize indentation for ast and gfql_validation
f275b92
@lmeyerov
fix(docs): correct indentation in AST.__call__/reverse
566b158
@lmeyerov
docs(rtd): exclude problematic memgraph and hop notebooks
5c7ca51
@lmeyerov
fix(docs): clean demo notebooks and reinclude in build
e4e46a6
@lmeyerov
fix(tests): dedupe static graphviz/mermaid cases
fb0f1c1
@lmeyerov
docs(memgraph): use raw.githubusercontent.com for IAM screenshots
69caf94
@lmeyerov
fix(docs): clean memgraph notebook and docstrings for rtd
2a70d14
@lmeyerov
chore(docs): clarify docs build call and graphviz render note
b8d4ec6
@lmeyerov
fix(ast): restore _validate_fields indentation
ca8f932
@lmeyerov
chore(ast): restore upstream formatting after rebase
c53a5a5
@lmeyerov
fix(docs): make ci.sh path-agnostic for CI
eed86af
@lmeyerov
chore(docs): guard graphviz build when dot missing
a350e43
@lmeyerov
fix(docs): avoid graphviz map file when dot missing
de233cb
@lmeyerov
fix(docs): set graphviz format per builder and pdf-safe placeholder
752724b
lmeyerov and others added 13 commits December 4, 2025 19:13
@lmeyerov
fix(docs): use real pdf placeholder when dot missing
23fb635
@lmeyerov @claude
fix(docs): switch RTD from commands to jobs to enable apt_packages
1bac50b 
The RTD build.commands option is incompatible with apt_packages,
causing graphviz to not be installed despite being listed. This
results in 'dot command cannot be run' warnings and placeholder
images instead of real Graphviz diagrams.

Switching to build.jobs allows apt_packages to work properly:
- post_install: copy demos and markdown files
- build.html/epub/pdf: format-specific sphinx builds

This should make Graphviz diagrams render correctly on RTD.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@lmeyerov @claude
fix(docs): add sphinx config key to RTD for proper install ordering
ea70584 
The sphinx.configuration key is needed to trigger RTD's Sphinx
support which ensures pip install runs before the build jobs.
Without it, sphinx-build is not available when build.jobs run.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@lmeyerov @claude
chore(docs): add warning when graphviz placeholder is triggered
af028dc 
Now that RTD properly installs graphviz via build.jobs + apt_packages,
the placeholder shim should rarely be needed. Add a one-time warning
when it does trigger to make it visible that diagrams are missing.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@lmeyerov @claude
fix(docs): remove graphviz placeholder shim - fail hard if dot missing
8ea5be4 
Remove the placeholder shim that silently masked missing graphviz.
Now if dot is unavailable, the build will fail loudly instead of
producing invisible 1x1 pixel placeholder images.

RTD now properly installs graphviz via build.jobs + apt_packages,
so the shim is no longer needed. Local builds without graphviz
will fail fast with a clear error message from Sphinx.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@lmeyerov @claude
docs(changelog): document RTD graphviz fix
50cf767 
🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@lmeyerov @claude
fix(docs): use svg:img for graphviz to fix rendering in browsers
29f41de 
The <object> tag used by default for SVG graphviz output doesn't
render reliably in all browsers. Switch to svg:img format which
embeds as <img> tag for more consistent display.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@lmeyerov @claude
fix(docs): revert to svg format (svg:img not supported in Sphinx 8.0)
ee323c7 
Sphinx 8.0.2 on RTD doesn't support svg:img format, causing graphviz
diagrams to be silently dropped. Revert to plain svg which uses
<object> tags - they render correctly, just need the file to exist.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@lmeyerov @claude
docs(plan): add PR split strategy for safe work preservation
1c0422e 
Phase 4 documents how to split PR #859 into:
- Base PR: infrastructure + minimal proof-of-work (1 RST, 1 MyST, 1 notebook)
- Stacked PR: rich graphviz examples across all docs

Includes safe workflow with backup tag before trimming.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@lmeyerov @claude
refactor(docs): trim to minimal graphviz proof-of-work examples
94dfdb0 
Keep infrastructure + 1 example each for RST/MyST/notebook:
- RST: gfql/about.rst (1 graphviz directive)
- MyST: gfql/spec/index.md (1 graphviz example)
- Notebook: graphviz/graphviz.ipynb (plot_static example)

Reverted graphviz additions from:
- 10min.rst
- visualization/10min.rst
- ecosystem.rst
- gfql/overview.rst
- gfql/quick.rst
- graphistry.layout.rst

These will be added in stacked PR feat/graphviz-docs-usage.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@lmeyerov
chore: trigger RTD rebuild after fixing backup tag name
a2cd74f
@lmeyerov
chore: trigger RTD rebuild after removing backup tag
6262dc8
@lmeyerov @claude
docs(plan): update Phase 4 status - PR split complete
7f26afb 
- Phase 4.A done: base branch trimmed to minimal examples
- Stacked branch feat/graphviz-docs-usage preserves full work
- Added lesson: backup tags break setuptools_scm, use branches instead
- CI/RTD green on trimmed base

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@lmeyerov lmeyerov force-pushed the feat/graphviz-docs-rendering branch from e0b3eb8 to 7f26afb Compare December 5, 2025 03:13
lmeyerov added a commit that referenced this pull request Dec 5, 2025
@lmeyerov @claude
docs: add graphviz examples across documentation
1f6a4bc 
Add rich graphviz diagrams to documentation pages:
- 10min.rst - intro visualization example
- visualization/10min.rst - layout pipeline diagram
- ecosystem.rst - ecosystem overview
- gfql/overview.rst - GFQL flow diagram
- gfql/quick.rst - quick start example
- graphistry.layout.rst - layout options

Builds on infrastructure from base PR #859.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@lmeyerov lmeyerov mentioned this pull request Dec 5, 2025
Open
2 tasks
@lmeyerov @claude
feat(plot_static): auto-display SVG/PNG in Jupyter notebooks
15f8cb5 
- Add _auto_display_static() helper with IPython environment detection
- Automatically display SVG/PNG output inline in Jupyter notebooks
- Still returns bytes for programmatic use (saving to disk)
- Update graphviz docs with simplified usage examples
- Update graphviz demo notebook with cleaner syntax

Users no longer need to manually wrap output with SVG() or Image():

  # Before: required explicit display wrapper
  from IPython.display import SVG
  svg = g.plot_static(format='svg')
  SVG(svg)

  # After: just works
  g.plot_static()

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
lmeyerov added a commit that referenced this pull request Dec 5, 2025
@lmeyerov @claude
docs: add graphviz examples across documentation
6f6c7a2 
Add rich graphviz diagrams to documentation pages:
- 10min.rst - intro visualization example
- visualization/10min.rst - layout pipeline diagram
- ecosystem.rst - ecosystem overview
- gfql/overview.rst - GFQL flow diagram
- gfql/quick.rst - quick start example
- graphistry.layout.rst - layout options

Builds on infrastructure from base PR #859.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@lmeyerov @claude
docs: add plot_static demo notebook with RTD execution
8242989 
Creates a minimal notebook that:
- Uses nbsphinx execute=always metadata
- Only requires local operations (no server registration)
- Demonstrates plot_static() SVG rendering, DOT output, and file saving
- RTD will execute this notebook fresh each build

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
lmeyerov added a commit that referenced this pull request Dec 5, 2025
@lmeyerov @claude
docs: add graphviz examples across documentation
e92a2c0 
Add rich graphviz diagrams to documentation pages:
- 10min.rst - intro visualization example
- visualization/10min.rst - layout pipeline diagram
- ecosystem.rst - ecosystem overview
- gfql/overview.rst - GFQL flow diagram
- gfql/quick.rst - quick start example
- graphistry.layout.rst - layout options

Builds on infrastructure from base PR #859.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@lmeyerov @claude
fix(docs): handle missing pygraphviz in plot_static demo notebook
79ace9b 
Add HAS_PYGRAPHVIZ check so notebook executes cleanly on RTD
where pygraphviz is not installed in the Python environment.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
lmeyerov added a commit that referenced this pull request Dec 5, 2025
@lmeyerov @claude
docs: add graphviz examples across documentation
648eaa1 
Add rich graphviz diagrams to documentation pages:
- 10min.rst - intro visualization example
- visualization/10min.rst - layout pipeline diagram
- ecosystem.rst - ecosystem overview
- gfql/overview.rst - GFQL flow diagram
- gfql/quick.rst - quick start example
- graphistry.layout.rst - layout options

Builds on infrastructure from base PR #859.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@lmeyerov @claude
fix(docs): add pygraphviz to RTD for live notebook execution
85243e1 
- Add graphviz-dev to apt_packages (headers for compilation)
- Add pygraphviz extra to pip install

This enables plot_static_demo.ipynb to render actual SVG graphs on RTD.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
lmeyerov added a commit that referenced this pull request Dec 5, 2025
@lmeyerov @claude
docs: add graphviz examples across documentation
3b0ca11 
Add rich graphviz diagrams to documentation pages:
- 10min.rst - intro visualization example
- visualization/10min.rst - layout pipeline diagram
- ecosystem.rst - ecosystem overview
- gfql/overview.rst - GFQL flow diagram
- gfql/quick.rst - quick start example
- graphistry.layout.rst - layout options

Builds on infrastructure from base PR #859.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@lmeyerov @claude
docs: add plot_static_demo notebook to toctree for RTD execution
8de5932 
🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
lmeyerov added a commit that referenced this pull request Dec 7, 2025
@lmeyerov @claude
docs: add graphviz examples across documentation
865390e 
Add rich graphviz diagrams to documentation pages:
- 10min.rst - intro visualization example
- visualization/10min.rst - layout pipeline diagram
- ecosystem.rst - ecosystem overview
- gfql/overview.rst - GFQL flow diagram
- gfql/quick.rst - quick start example
- graphistry.layout.rst - layout options

Builds on infrastructure from base PR #859.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@lmeyerov