Docs: merge getting-started pages and tidy the manual

.github/workflows/render-docs.yml

@@ -82,6 +82,6 @@ jobs:
         run: |
           npm ci
           npm run verify
-          # Antora 3.1.x silently exits 0 without generating anything on
-          # non-LTS Node (e.g. 26); guard against that silent no-op.
+          # Antora can exit 0 without generating a site (observed with Antora
+          # 3.1.x on newer Node); guard against that silent no-op.
           test -f build/site/index.html || { echo '::error::Antora did not generate a site'; exit 1; }

MANIFEST.in

@@ -1 +1 @@
-include examples/example_graph.png
+include examples/images/example_graph.png

README.md

@@ -16,7 +16,7 @@ Alternatively, you can export the output to a file and view it in a web browser.
 
 The package wraps the [Neo4j Visualization JavaScript library (NVL)](https://neo4j.com/docs/nvl/current/).
 
-![Example Graph](examples/example_graph.png)
+![Example Graph](examples/images/example_graph.png)
 
 ## Some notable features
 

docs/.gitignore

@@ -3,3 +3,4 @@ build
 # Antora docs
 antora/node_modules/
 source/tutorials/*.png
+source/tutorials/images/

docs/antora/modules/ROOT/content-nav.adoc

@@ -1,6 +1,4 @@
 * xref:index.adoc[]
-* xref:installation.adoc[]
-* xref:getting-started.adoc[]
 * xref:rendering.adoc[]
 * xref:customizing.adoc[]
 * xref:integration/index.adoc[]

docs/antora/modules/ROOT/pages/customizing.adoc

@@ -7,7 +7,7 @@ relationships of existing `VisualizationGraph` objects.
 
 If you have not yet created a `VisualizationGraph` object, refer to one of the following sections:
 
-* xref:getting-started.adoc[Getting started] for creating a visualization graph from scratch using `neo4j-viz`
+* xref:index.adoc[Getting started] for creating a visualization graph from scratch using `neo4j-viz`
   primitives like link:{api-docs-uri}/node/[Node] and link:{api-docs-uri}/relationship/[Relationship] and
   link:{api-docs-uri}/visualization-graph[`VisualizationGraph`] directly.
 * xref:integration/index.adoc[] for importing data from a Pandas DataFrame or Neo4j GDS projection.
@@ -108,7 +108,7 @@ from palettable.wesanderson import Moonrise1_5
 VG.color_nodes(field="caption", colors=Moonrise1_5.colors)  # ColorSpace.DISCRETE is default
 ----
 
-In theses cases, all items with the same field value will get the same color.
+In these cases, all items with the same field value will get the same color.
 
 If there are fewer colors than unique values for the `field` or `property` provided, the colors will be reused in a cycle.
 To avoid that, you could use a larger palette or extend one with additional colors.
@@ -138,8 +138,8 @@ VG.color_relationships(
 )
 ----
 
-In these cases, the nodes or relationships will be colored based on the value of the property, with the lowest values being colored with the first color and the highest values being colored with the last color.
-Since we only provided five colors in the range, the granularity of the gradient will be limited to five steps.
+The property values are min-max scaled, and each node or relationship is then colored by interpolating smoothly along the gradient: the lowest value gets the first color, the highest gets the last color, and values in between are blends of the neighboring color stops.
+The number of stops controls the shape of the gradient (for example a multi-hue one), not the number of distinct colors.
 
 `palettable` and `matplotlib` are great libraries to use to create custom color gradients.
 
@@ -253,7 +253,7 @@ In the following example, we pin the node with ID 1337 and unpin the node with I
 [source, python]
 ----
 # VG is a VisualizationGraph object
-VG.toggle_nodes_pinned(1337: True, 42: False)})
+VG.toggle_nodes_pinned({1337: True, 42: False})
 ----
 
 == Reading the selection

docs/antora/modules/ROOT/pages/index.adoc

@@ -1,4 +1,5 @@
-= Introduction
+= Getting started
+:page-aliases: installation.adoc, getting-started.adoc
 
 The Python Graph Visualization library allows you to visualize graph data interactively in Python.
 
@@ -10,4 +11,116 @@ The library wraps the JavaScript-based link:https://neo4j.com/docs/nvl/current/[
 * xref:integration/snowflake.adoc[]
 
 The source code is available on link:https://github.com/neo4j/python-graph-visualization[GitHub].
-If you have a suggestion on how we can improve the library or want to report a problem, you can create a link:https://github.com/neo4j/python-graph-visualization/issues/new[new issue].
+If you have a suggestion on how we can improve the library or want to report a problem, you can create a link:https://github.com/neo4j/python-graph-visualization/issues/new[new issue].
+
+== Installation
+
+You can install the latest version of the library with `pip`:
+
+[source, console]
+----
+pip install neo4j-viz
+----
+
+=== Optional dependencies
+
+There are a few optional dependencies that you can install to enable additional features of the library.
+The link:{tutorials-docs-uri}[tutorials] install any additional dependencies they need in their first notebook cells, so there is nothing extra to install to follow along.
+
+==== Integration with external sources
+
+The library can import data directly from xref:integration/index.adoc[external sources].
+Each integration page includes installation instructions for the needed dependencies.
+
+== Creating your first visualization
+
+In this section, we will cover the very basics of creating a visualization graph using the `neo4j-viz` library.
+We will use a small toy graph representing the purchase history of a few people and products.
+
+We start by instantiating the link:{api-docs-uri}/node/[Nodes] and link:{api-docs-uri}/relationship[Relationships] we want in our graph.
+The only mandatory fields for a node are the “id”, and “source” and “target” for a relationship.
+But the other fields can optionally be used to customize the appearance of the nodes and relationships in the visualization.
+
+Lastly we create a link:{api-docs-uri}/visualization-graph/[VisualizationGraph] object with the nodes and relationships we created, and call its `render_widget` method to display the graph as an interactive widget.
+
+[source, python, role=nocollapse]
+----
+from neo4j_viz import Node, Relationship, VisualizationGraph
+
+nodes = [
+    Node(id=0, size=10, caption="Person"),
+    Node(id=1, size=10, caption="Product"),
+    Node(id=2, size=20, caption="Product"),
+    Node(id=3, size=10, caption="Person"),
+    Node(id=4, size=10, caption="Product"),
+]
+
+relationships = [
+    Relationship(
+        source=0,
+        target=1,
+        caption="BUYS",
+    ),
+    Relationship(
+        source=0,
+        target=2,
+        caption="BUYS",
+    ),
+    Relationship(
+        source=3,
+        target=2,
+        caption="BUYS",
+    ),
+]
+
+VG = VisualizationGraph(nodes=nodes, relationships=relationships)
+
+VG.render_widget(initial_zoom=2)
+----
+
+[TIP]
+====
+See the link:{tutorials-docs-uri}/getting-started/[Getting started tutorial] to interact with the graph.
+====
+
+image::getting-started-widget.png["The graph rendered as an interactive widget"]
+
+NOTE: `render_widget` is the recommended way to display a graph: it returns an interactive widget with two-way sync between Python and the browser, and features such as adding data to a graph that is already displayed, changing the layout or zoom dynamically, and reacting to selections and clicks are only available through it.
+The `render` method instead returns a static HTML object and is not recommended for interactive use; see xref:rendering.adoc[Rendering a graph] for the full list of options.
+
+As we can see in the graph above, the radius of one of the nodes is larger than the others.
+This is because we set the “size” field of the node to 20, while the others are set to 10.
+
+At this time the nodes are colored using the default colors.
+If we want to distinguish between the different types of nodes, we can color them differently with the `color_nodes` method. 
+We can pass the field we want to use to color the nodes as an argument.
+In this case, we will use the "caption" field.
+Nodes with the same "caption" will have the same color.
+We will use the default color scheme, which is the Neo4j color scheme.
+
+[source, python]
+----
+VG.color_nodes(field="caption")
+
+VG.render_widget(initial_zoom=2)
+----
+
+[TIP]
+====
+See the link:{tutorials-docs-uri}/getting-started/[Getting started tutorial] to interact with the graph.
+====
+
+image::getting-started-widget-colored.png["The graph with nodes colored by caption"]
+
+We are now easily able to distinguish between the different types of nodes in the graph.
+
+== Next steps
+
+Now that we have covered the basics of creating and rendering a visualization graph, we can move on to more advanced topics.
+
+Here are some suggestions for what to do next:
+
+* Browse the link:{tutorials-docs-uri}[tutorials] for more examples and use cases
+* Learn about the xref:integration/index.adoc[integrations] with other libraries such as Neo4j GDS and Pandas
+* Check out the xref:rendering.adoc[rendering options] and convenience methods of `VisualizationGraph`
+* Read about our link:{api-docs-uri}/[API reference]

docs/antora/modules/ROOT/pages/integration/gds.adoc

@@ -1,7 +1,7 @@
 = Neo4j Graph Data Science
 
 The `neo4j-viz` library provides a convenience method for importing data from the link:https://neo4j.com/docs/graph-data-science/current/[Neo4j Graph Data Science] (GDS) library.
-It requires and additional dependency to be installed, which you can do by running:
+It requires an additional dependency to be installed, which you can do by running:
 
 [source, console]
 ----
@@ -52,6 +52,8 @@ VG.resize_nodes(property="pagerank")
 # Color the nodes by the `componentId` property, so that the nodes are
 # colored by the connected component they belong to
 VG.color_nodes(property="componentId")
+
+VG.render_widget()
 ----
 
 See the link:{tutorials-docs-uri}/gds-example[Visualizing Neo4j Graph Data Science (GDS) Graphs tutorial] for a more extensive example.

docs/antora/modules/ROOT/pages/integration/neo4j.adoc

@@ -1,7 +1,7 @@
 = Neo4j database
 
 The `neo4j-viz` library provides a convenience method for importing data from the Neo4j database via the link:https://neo4j.com/docs/python-manual/current/[Neo4j Python driver].
-It requires and additional dependency to be installed, which you can do by running:
+It requires an additional dependency to be installed, which you can do by running:
 
 [source, console]
 ----
@@ -13,18 +13,18 @@ to import query results from Neo4j.
 
 The `from_neo4j` method takes one mandatory positional parameter: A `data` argument representing either a query result in the shape of a `neo4j.graph.Graph`, `neo4j.EagerResult` or `neo4j.Result`, or a `neo4j.Driver` in which case a simple default query will be executed internally to retrieve the graph data.
 
-The optional `max_rows` parameter can be used to limit the number of relationships shown in the visualization.
+The optional `row_limit` parameter can be used to limit the number of relationships shown in the visualization.
 By default, it is set to 10.000, meaning that if the database has more than 10.000 rows, a warning will be raised.
 Note, this only applies if the `data` parameter is a `neo4j.Driver`.
 
 == Example
 
-In this small example, we import a graph from a Neo4j query result.
+In this small example, we import a graph from a Neo4j query result and display it as an interactive widget.
 
 [source, python]
 ----
-from neo4j import GraphDatabase, RoutingControl, Result
-from neo4j_viz.gds import from_gds
+from neo4j import GraphDatabase, RoutingControl
+from neo4j_viz.neo4j import from_neo4j
 
 # Modify this to match your Neo4j instance's URI and credentials
 URI = "neo4j://localhost:7687"
@@ -39,6 +39,8 @@ with GraphDatabase.driver(URI, auth=auth) as driver:
     )
 
 VG = from_neo4j(result)
+
+VG.render_widget()
 ----
 
 See the link:{tutorials-docs-uri}/neo4j-example[Visualizing Neo4j Graphs tutorial] for a more extensive example.