Repository navigation
Docs: merge getting-started pages and tidy the manual - #496
Merged
Merged
Conversation
- Merge the Introduction, Installation and Getting started pages into a single "Getting started" page, with page-aliases so the old /installation/ and /getting-started/ URLs keep redirecting - Lead "Rendering a graph" with render_widget and demote render to the static/export path; drop the documented-but-nonexistent show_hover_tooltip parameter - Fix the integration examples: the Neo4j import, the from_neo4j row_limit name, from_dfs naming, a missing Snowflake session, and end each example with render_widget() - Clarify continuous color-space interpolation and fix the toggle_nodes_pinned example in "Customizing the visualization" - Fix the GDS tutorial's Credentials heading level (Sphinx warning)
Group the notebook and README images under examples/images/ so the example notebooks are easier to find. Update the notebook image references, the .nblink extra-media entries (now the images directory), MANIFEST.in and both READMEs, and ignore the subfolder nbsphinx_link copies into the docs tree.
FlorentinD
commented
Oct 30, 2026
`pip install neo4j-viz[notebook]` documents an extra that does not exist (`notebook` is a uv dependency-group, not a project extra), so pip only warns and installs the base package. Every tutorial installs what it needs in its first notebook cells anyway.
The docs/antora engines cap below Node 26 was added because Antora 3.1.x silently no-ops on Node 26. Antora was bumped to 3.2.1 shortly after, and Node 26.13.0 now builds the site identically to Node 24 (only sitemap timestamps differ), so widen the range to match js-applet. The eMudhra-patched floor (>=26.12.1) is preserved, and the silent-no-op guard in the workflow is kept.
Add an install cell to the getting-started tutorial (it had none), and install neo4j-viz itself in the GDS tutorial (it was missing, so the notebook would ImportError on a fresh Colab runtime). Consolidate each notebook's install steps into a single `%pip install "neo4j-viz[extra]" ...` using the extras the integration pages document.
FlorentinD
marked this pull request as ready for review
October 30, 2026 14:41
The widget browser tests intermittently hung with a cell stuck showing [*]: while its kernel sat idle — the run command had gone to a session that was still being wired up (the previous test's kernel was still being torn down), so the kernel never executed the cell. While waiting for a cell the harness now also polls the kernel's execution state: if the kernel never picks the run up, the cell is re-issued via the toolbar Run button (which a focus-stealing dialog cannot swallow). Cells the kernel did run are left alone — the frontend prompt can lag well behind the kernel (e.g. while rendering an image for save()), and re-issuing those would just restart the work. Timeout errors now include the prompt and kernel state. Also shut down each notebook's session after a run so its kernel does not outlive it and interfere with the next notebook on the same server.
Retrying a cell whose run never reached the kernel made things worse in CI: the kernel-state polling can miss a short busy window, so the retry fired spuriously and every Python matrix job failed. Restore the previous prompt-based wait (unchanged behaviour) and keep only: - best-effort session shutdown after a run, so a kernel does not outlive it, - richer failure output (the sessions JSON and the browser console tail), since the pytest tmp artifacts never reach CI logs and these failures are frontend/kernel communication problems.
The widget browser tests intermittently hang with a cell stuck showing [*]: while its kernel sits idle — the JupyterLab frontend failed to reach the kernel, so the run never executed, and re-issuing the cell does not help because the request still cannot get through. Retry the whole run instead: a failed run is repeated from scratch — a fresh notebook, page, and kernel — up to NOTEBOOK_RUN_ATTEMPTS. BrowserUnavailable still propagates so callers can skip. Verified with a temporary test that fails on the first attempt and passes on the retry.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Follow-up docs work for GDS-260; the first part landed in #494.
What changed
index.adoc), withpage-aliasesso the old/installation/and/getting-started/URLs keep redirecting. The two old pages and their nav entries are removed.render_widget(recommended, two-way sync, widget-only features) and demotesrenderto the static/embed/export path. Removed the documented-but-nonexistentshow_hover_tooltipparameter.from_neo4j),from_neo4j'srow_limitparameter name,from_dfsnaming, a missing Snowflake session +import os, and a brokencustomizinglink. Each example now ends withrender_widget().toggle_nodes_pinnedexample.Credentialsheading level (removes a Sphinx build warning).examples/images/so the notebooks are easier to find.Notes
Verification
npm run verify(fails on warnings) — cleanruff check/ruff format --checkand the notebook formatting check — pass