From cc897a3f07c1c5f8329dff229ccdca459c832b8c Mon Sep 17 00:00:00 2001
From: Anthony Mahanna <anthony.mahanna@arangodb.com>
Date: Wed, 29 Oct 2025 10:28:40 -0400
Subject: [PATCH] doc updates

---
 README.md       | 32 +++++++++++++++++++++
 doc/convert.rst | 75 +++++++++++++++++++++++++++++++++++++++++++++++++
 doc/index.rst   |  3 +-
 3 files changed, 109 insertions(+), 1 deletion(-)
 create mode 100644 doc/convert.rst

diff --git a/README.md b/README.md
index cb48011..2431a26 100644
--- a/README.md
+++ b/README.md
@@ -204,3 +204,35 @@ G_nxadb = nxadb.Graph(
 assert G_nxadb.number_of_nodes() == G_nx.number_of_nodes()
 assert G_nxadb.number_of_edges() == G_nx.number_of_edges()
 ```
+
+## Direct Conversion Helpers
+
+Use the conversion helpers in `nx_arangodb.convert` to move between ecosystems while preserving directed/multi properties.
+
+```python
+import networkx as nx
+import nx_arangodb as nxadb
+
+# Start with a NetworkX graph
+G_nx = nx.karate_club_graph()
+
+# Convert to nx-arangodb (optionally force directed via as_directed=True)
+G_adb = nxadb.convert._to_nxadb_graph(G_nx)
+
+# Convert back to NetworkX
+G_nx2 = nxadb.convert._to_nx_graph(G_adb)
+
+# Convert to nx-cugraph (if installed)
+try:
+    G_cg = nxadb.convert._to_nxcg_graph(G_adb)
+except NotImplementedError:
+    # nx-cugraph/CuPy not available in this environment
+    pass
+```
+
+Notes:
+- Database-backed graphs: converting `nxadb.Graph` to NetworkX will fetch node and adjacency dictionaries from ArangoDB and build a plain NetworkX graph.
+- Local `nxadb.Graph` (not yet persisted) is already NetworkX-compatible and may be returned as-is.
+- `as_directed` forces directed variants without changing multiplicity.
+- GPU conversions require `nx-cugraph` and CuPy; otherwise `_to_nxcg_graph` raises `NotImplementedError`.
+- When converting to `nx-cugraph`, enabling `G_adb.use_nxcg_cache = True` caches the constructed GPU graph for reuse.
diff --git a/doc/convert.rst b/doc/convert.rst
new file mode 100644
index 0000000..4ed970a
--- /dev/null
+++ b/doc/convert.rst
@@ -0,0 +1,75 @@
+Conversions between NetworkX, nx-arangodb, and nx-cugraph
+=========================================================
+
+This page describes how to convert graphs across ecosystems using
+``nx_arangodb.convert`` for interoperability and performance.
+
+Overview
+--------
+
+- ``_to_nx_graph``: ``nxadb.Graph`` | ``nx.Graph`` -> ``nx.Graph``
+- ``_to_nxadb_graph``: ``nx.Graph`` | ``nxadb.Graph`` -> ``nxadb.Graph``
+- ``_to_nxcg_graph``: ``nxadb.Graph`` | ``nxcg.Graph`` -> ``nxcg.Graph``
+  (requires ``nx-cugraph`` and CuPy)
+
+Behavior notes
+--------------
+
+- Database-backed ``nxadb`` graphs: converting to NetworkX pulls node and
+  adjacency dictionaries from ArangoDB and constructs a plain NetworkX graph.
+- Local ``nxadb`` graphs (``graph_exists_in_db`` is ``False``) are already
+  NetworkX-compatible and may be returned as-is.
+- Directed/multi settings are preserved; ``as_directed`` forces directed
+  variants without changing multiplicity.
+- If ``nx-cugraph`` or CuPy is unavailable, GPU conversions are disabled and
+  ``_to_nxcg_graph`` raises ``NotImplementedError``.
+
+Performance and caching
+-----------------------
+
+- Database pulls are timed and logged.
+- ``nxadb_to_nx`` returns a standard NetworkX graph and does not re-wrap the
+  custom dict implementations in ``nx_arangodb.classes.dict``.
+- ``nxadb_to_nxcg`` can cache the constructed GPU graph when
+  ``G.use_nxcg_cache`` is ``True`` on the ``nxadb.Graph`` instance.
+
+Examples
+--------
+
+.. code-block:: python
+
+   import networkx as nx
+   import nx_arangodb as nxadb
+
+   # Start with a NetworkX graph
+   G_nx = nx.karate_club_graph()
+
+   # Convert to nx-arangodb (optionally force directed)
+   G_adb = nxadb.convert._to_nxadb_graph(G_nx, as_directed=False)
+
+   # Convert back to NetworkX
+   G_nx2 = nxadb.convert._to_nx_graph(G_adb)
+
+   # Convert to nx-cugraph if available
+   try:
+       G_cg = nxadb.convert._to_nxcg_graph(G_adb)
+   except NotImplementedError:
+       # nx-cugraph/CuPy not available
+       pass
+
+API Reference
+-------------
+
+.. autofunction:: nx_arangodb.convert._to_nx_graph
+
+.. autofunction:: nx_arangodb.convert._to_nxadb_graph
+
+.. autofunction:: nx_arangodb.convert._to_nxcg_graph
+
+.. autofunction:: nx_arangodb.convert.nx_to_nxadb
+
+.. autofunction:: nx_arangodb.convert.nxadb_to_nx
+
+.. autofunction:: nx_arangodb.convert.nxadb_to_nxcg
+
+
diff --git a/doc/index.rst b/doc/index.rst
index 9883485..2e9d429 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -124,4 +124,5 @@ Expect documentation to grow over time:
    classes/index
    dict/index
    algorithms/index
-   views/index
\ No newline at end of file
+   views/index
+   convert
\ No newline at end of file