RTD Prep (#55)

* docs | wip

* fix: `nx_to_nxadb`

* fix: doc

* checkpoint

* checkpoint 2

* fix: docstrings

* checkpoint 3

* fix: hyperlinks

* mv: workflows

.github/disabled-workflows/docs.yaml → .github/workflows/docs.yaml

@@ -20,7 +20,7 @@ jobs:
           python-version: '3.10'
 
       - name: Install dependencies
-        run: pip install .[dev] && pip install -r docs/requirements.txt
+        run: pip install .[dev] && pip install -r doc/requirements.txt
 
       - name: Generate Sphinx HTML
-        run: cd docs && make html
+        run: cd doc && make html

.gitignore

@@ -25,6 +25,15 @@ wheels/
 *.egg
 MANIFEST
 
+# Generated while building documentation.
+doc/auto_examples
+doc/modules
+doc/generated
+doc/algorithms/generated
+doc/classes/generated
+doc/readwrite/generated
+doc/path.to.file
+
 # PyInstaller
 #  Usually these files are written by a python script from a template
 #  before PyInstaller builds the exe, so as to inject date/other infos into it.
@@ -64,7 +73,7 @@ instance/
 .scrapy
 
 # Sphinx documentation
-docs/_build/
+doc/_build/
 
 # PyBuilder
 target/

.readthedocs.yaml

@@ -11,9 +11,9 @@ build:
   tools:
     python: "3.12"
 
-# Build documentation in the "docs/" directory with Sphinx
+# Build documentation in the "doc/" directory with Sphinx
 sphinx:
-  configuration: docs/conf.py
+  configuration: doc/conf.py
   fail_on_warning: true
 
 # Optionally build your docs in additional formats such as PDF and ePub
@@ -26,4 +26,4 @@ sphinx:
 # See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
 python:
    install:
-   - requirements: docs/requirements.txt
+   - requirements: doc/requirements.txt

README.md

@@ -2,15 +2,23 @@
 
 
 <div style="display: flex; align-items: center; gap: 10px;">
-    <img src="https://avatars.githubusercontent.com/u/388785?s=200&v=4" alt="NetworkX" style="height: 60px;">
-    <img src="https://arangodb.com/wp-content/uploads/2016/05/[email protected]" alt="ArangoDB" style="height: 60px;">
-    <img src="https://rapids.ai/images/RAPIDS-logo.png" alt="RAPIDS" style="height: 60px;">
-    <img src="https://insights.virti.com/content/images/2021/09/20181218-Nvidia-Inception.png" alt="NVIDIA" style="height: 60px;">
+    <a href="https://networkx.github.io/">
+        <img src="https://avatars.githubusercontent.com/u/388785?s=200&v=4" alt="NetworkX" style="height: 60px;">
+    </a>
+    <a href="https://www.arangodb.com/">
+        <img src="https://arangodb.com/wp-content/uploads/2016/05/[email protected]" alt="ArangoDB" style="height: 60px;">
+    </a>
+    <a href="https://rapids.ai/">
+        <img src="https://rapids.ai/images/RAPIDS-logo.png" alt="RAPIDS" style="height: 60px;">
+    </a>
+    <a href="https://www.nvidia.com/en-us/startups/">
+        <img src="https://insights.virti.com/content/images/2021/09/20181218-Nvidia-Inception.png" alt="NVIDIA" style="height: 60px;">
+    </a>
 </div>
 
 <br>
 
-<a href="https://colab.research.google.com/github/arangodb/nx-arangodb/blob/main/docs/nx_arangodb.ipynb" target="_parent"><img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/></a>
+<a href="https://colab.research.google.com/github/arangodb/nx-arangodb/blob/main/doc/nx_arangodb.ipynb" target="_parent"><img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/></a>
 [![CircleCI](https://dl.circleci.com/status-badge/img/gh/arangodb/nx-arangodb/tree/main.svg?style=svg)](https://dl.circleci.com/status-badge/redirect/gh/arangodb/nx-arangodb/tree/main)
 [![CodeQL](https://github.com/arangodb/nx-arangodb/actions/workflows/analyzee.yaml/badge.svg)](https://github.com/arangodb/nx-arangodb/actions/workflows/analyzee.yaml)
 [![Docs](https://github.com/arangodb/nx-arangodb/actions/workflows/docs.yaml/badge.svg)](https://github.com/arangodb/nx-arangodb/actions/workflows/docs.yaml)
@@ -44,7 +52,7 @@ Benefits of having ArangoDB as a backend to NetworkX include:
 6. Access to efficient distribution of graph data ([ArangoDB SmartGraphs](https://docs.arangodb.com/stable/graphs/smartgraphs/)).
 
 <p align="center">
-    <img src="./docs/_static/nxadb.png" style="height: 200px;">
+    <img src="./doc/_static/nxadb.png" style="height: 200px;">
 </p>
 
 
@@ -169,7 +177,7 @@ nx.config.backends.arangodb.use_gpu = True
 ```
 
 <p align="center">
-    <img src="./docs/_static/dispatch.png" style="height: 200px;">
+    <img src="./doc/_static/dispatch.png" style="height: 200px;">
 </p>
 
 

doc/algorithms/index.rst

@@ -0,0 +1,99 @@
+.. _algorithms:
+
+**********
+Algorithms
+**********
+
+As NetworkX-ArangoDB is primarily a **Storage Backend** to NetworkX, its primary focus is on persisting and reloading graphs from ArangoDB.
+
+However, running algorithms on the graph is also still possible.
+
+There are 3 ways to run algorithms on the graph:
+
+1. **NetworkX**: The traditional way of running algorithms on Graphs.
+2. **NetworkX-cuGraph**: The GPU-accelerated way of running algorithms on Graphs.
+3. **ArangoDB**: The database way of running algorithms on Graphs.
+
+Currently, Options 1 & 2 are supported, whereas Option 3 is a work-in-progress.
+
+Running algorithms with Option 2 requires ``nx-cugraph`` to be installed on a system with a compatible GPU:
+
+.. code-block::
+
+   pip install nx-cugraph-cu12 --extra-index-url https://pypi.nvidia.com
+
+When running algorithms with Option 2, the graph is converted to a ``nx-cugraph`` graph, and the algorithm is run on the GPU.
+
+This is only possible if ``nx-cugraph`` has implemented the algorithm you want to run.
+
+- For a list of algorithms that are supported by ``nx-cugraph``, refer to the `nx-cugraph README <https://github.com/rapidsai/cugraph/tree/branch-24.10/python/nx-cugraph#algorithms>`_.
+- For a list of algorithms that are supported by ``networkx``, refer to the `NetworkX Documentation <https://networkx.org/documentation/stable/reference/algorithms/index.html>`_.
+
+``nx-arangodb`` will automatically dispatch algorithm calls to either CPU or GPU based on if ``nx-cugraph`` is installed. We rely on a rust-based library called `phenolrs <https://github.com/arangoml/phenolrs>`_ to retrieve ArangoDB Graphs as fast as possible.
+
+You can also force-run algorithms on CPU even if ``nx-cugraph`` is installed:
+
+.. code-block:: python
+
+   import os
+   import networkx as nx
+   import nx_arangodb as nxadb
+
+   # os.environ ...
+
+   G = nxadb.Graph(name="MyGraph")
+
+   nx.config.backends.arangodb.use_gpu = False
+
+   nx.pagerank(G)
+   nx.betweenness_centrality(G)
+   # ...
+
+   nx.config.backends.arangodb.use_gpu = True
+
+
+.. image:: ../_static/dispatch.png
+   :align: center
+   :alt: nx-arangodb dispatching
+   :height: 200px
+
+
+**Tip**: If you're running multiple CPU algorithms, it's recommended to rely on invoking ``nxadb.convert.nxadb_to_nx`` to convert the graph to a NetworkX Graph before running the algorithms.
+This is because we currently load the entire graph into memory before running *each* algorithm, which can be slow for large graphs.
+
+.. code-block:: python
+
+   import networkx as nx
+   import nx_arangodb as nxadb
+
+   G_adb = nxadb.Graph(name="MyGraph")
+
+   G_nx = nxadb.convert.nxadb_to_nx(G)
+
+   nx.pagerank(G_nx)
+   nx.betweenness_centrality(G_nx)
+   # ...
+
+
+**Option 3**
+
+This is an experimental module seeking to provide server-side algorithms for `nx-arangodb` Graphs.
+The goal is to provide a set of algorithms that can be delegated to the server for processing,
+rather than having to pull all the data to the client and process it there.
+
+Currently, the module is in a very early stage and only provides a single algorithm: `shortest_path`.
+This is simply to demonstrate the potential of the module and to provide a starting point for further development.
+
+.. code-block:: python
+
+    import os
+    import networkx as nx
+    from nx_arangodb as nxadb
+
+    # os.environ ...
+
+    G = nxadb.Graph(name="MyGraph")
+
+    nx.pagerank(G) # Runs on the client
+    nx.shortest_path(G, source="A", target="B") # Runs on the DB server
+    nx.shortest_path.orig_func(G, source="A", target="B") # Runs on the client

doc/classes/digraph.rst

@@ -0,0 +1,89 @@
+.. _digraph:
+
+=======
+DiGraph
+=======
+
+Overview
+========
+.. currentmodule:: nx_arangodb
+.. autoclass:: DiGraph
+   :members: query, chat
+
+
+Methods
+=======
+
+Adding and removing nodes and edges
+-----------------------------------
+
+.. autosummary::
+   :toctree: generated/
+
+   DiGraph.__init__
+   DiGraph.add_node
+   DiGraph.add_nodes_from
+   DiGraph.remove_node
+   DiGraph.remove_nodes_from
+   DiGraph.add_edge
+   DiGraph.add_edges_from
+   DiGraph.add_weighted_edges_from
+   DiGraph.remove_edge
+   DiGraph.remove_edges_from
+   DiGraph.update
+   DiGraph.clear
+   DiGraph.clear_edges
+
+
+
+Reporting nodes edges and neighbors
+-----------------------------------
+.. autosummary::
+   :toctree: generated/
+
+   DiGraph.nodes
+   DiGraph.__iter__
+   DiGraph.has_node
+   DiGraph.__contains__
+   DiGraph.edges
+   DiGraph.out_edges
+   DiGraph.in_edges
+   DiGraph.has_edge
+   DiGraph.get_edge_data
+   DiGraph.neighbors
+   DiGraph.adj
+   DiGraph.__getitem__
+   DiGraph.successors
+   DiGraph.succ
+   DiGraph.predecessors
+   DiGraph.pred
+   DiGraph.adjacency
+   DiGraph.nbunch_iter
+
+
+Counting nodes edges and neighbors
+----------------------------------
+.. autosummary::
+   :toctree: generated/
+
+   DiGraph.order
+   DiGraph.number_of_nodes
+   DiGraph.__len__
+   DiGraph.degree
+   DiGraph.in_degree
+   DiGraph.out_degree
+   DiGraph.size
+   DiGraph.number_of_edges
+
+
+Making copies and subgraphs
+---------------------------
+.. autosummary::
+   :toctree: generated/
+
+   DiGraph.copy
+   DiGraph.to_undirected
+   DiGraph.to_directed
+   DiGraph.subgraph
+   DiGraph.edge_subgraph
+   DiGraph.reverse

doc/classes/graph.rst

@@ -0,0 +1,81 @@
+.. _graph:
+
+=====
+Graph
+=====
+
+Overview
+========
+.. currentmodule:: nx_arangodb
+.. autoclass:: Graph
+   :members: query, chat
+
+
+Methods
+=======
+
+Adding and removing nodes and edges
+-----------------------------------
+
+.. autosummary::
+   :toctree: generated/
+
+   Graph.__init__
+   Graph.add_node
+   Graph.add_nodes_from
+   Graph.remove_node
+   Graph.remove_nodes_from
+   Graph.add_edge
+   Graph.add_edges_from
+   Graph.add_weighted_edges_from
+   Graph.remove_edge
+   Graph.remove_edges_from
+   Graph.update
+   Graph.clear
+   Graph.clear_edges
+
+
+
+Reporting nodes edges and neighbors
+-----------------------------------
+.. autosummary::
+   :toctree: generated/
+
+   Graph.nodes
+   Graph.__iter__
+   Graph.has_node
+   Graph.__contains__
+   Graph.edges
+   Graph.has_edge
+   Graph.get_edge_data
+   Graph.neighbors
+   Graph.adj
+   Graph.__getitem__
+   Graph.adjacency
+   Graph.nbunch_iter
+
+
+
+Counting nodes edges and neighbors
+----------------------------------
+.. autosummary::
+   :toctree: generated/
+
+   Graph.order
+   Graph.number_of_nodes
+   Graph.__len__
+   Graph.degree
+   Graph.size
+   Graph.number_of_edges
+
+
+Making copies and subgraphs
+---------------------------
+.. autosummary::
+   :toctree: generated/
+
+   Graph.copy
+   Graph.to_undirected
+   Graph.to_directed
+   Graph.subgraph
+   Graph.edge_subgraph