Skip to content

Commit e978636

Browse files
aMahannaaMahanna
authored
RTD Prep (#55)
* docs | wip * fix: `nx_to_nxadb` * fix: doc * checkpoint * checkpoint 2 * fix: docstrings * checkpoint 3 * fix: hyperlinks * mv: workflows
1 parent ede0b82 commit e978636

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

44 files changed

+2329
-278
lines changed

‎.github/disabled-workflows/docs.yaml renamed to ‎.github/workflows/docs.yaml

+2-2
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ jobs:
2020
python-version: '3.10'
2121

2222
- name: Install dependencies
23-
run: pip install .[dev] && pip install -r docs/requirements.txt
23+
run: pip install .[dev] && pip install -r doc/requirements.txt
2424

2525
- name: Generate Sphinx HTML
26-
run: cd docs && make html
26+
run: cd doc && make html

‎.github/disabled-workflows/release.yml renamed to ‎.github/workflows/release.yml

File renamed without changes.

‎.gitignore

+10-1
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,15 @@ wheels/
2525
*.egg
2626
MANIFEST
2727

28+
# Generated while building documentation.
29+
doc/auto_examples
30+
doc/modules
31+
doc/generated
32+
doc/algorithms/generated
33+
doc/classes/generated
34+
doc/readwrite/generated
35+
doc/path.to.file
36+
2837
# PyInstaller
2938
# Usually these files are written by a python script from a template
3039
# before PyInstaller builds the exe, so as to inject date/other infos into it.
@@ -64,7 +73,7 @@ instance/
6473
.scrapy
6574

6675
# Sphinx documentation
67-
docs/_build/
76+
doc/_build/
6877

6978
# PyBuilder
7079
target/

‎.readthedocs.yaml

+3-3
Original file line numberDiff line numberDiff line change
@@ -11,9 +11,9 @@ build:
1111
tools:
1212
python: "3.12"
1313

14-
# Build documentation in the "docs/" directory with Sphinx
14+
# Build documentation in the "doc/" directory with Sphinx
1515
sphinx:
16-
configuration: docs/conf.py
16+
configuration: doc/conf.py
1717
fail_on_warning: true
1818

1919
# Optionally build your docs in additional formats such as PDF and ePub
@@ -26,4 +26,4 @@ sphinx:
2626
# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
2727
python:
2828
install:
29-
- requirements: docs/requirements.txt
29+
- requirements: doc/requirements.txt

‎README.md

+15-7
Original file line numberDiff line numberDiff line change
@@ -2,15 +2,23 @@
22

33

44
<div style="display: flex; align-items: center; gap: 10px;">
5-
<img src="https://avatars.githubusercontent.com/u/388785?s=200&v=4" alt="NetworkX" style="height: 60px;">
6-
<img src="https://arangodb.com/wp-content/uploads/2016/05/[email protected]" alt="ArangoDB" style="height: 60px;">
7-
<img src="https://rapids.ai/images/RAPIDS-logo.png" alt="RAPIDS" style="height: 60px;">
8-
<img src="https://insights.virti.com/content/images/2021/09/20181218-Nvidia-Inception.png" alt="NVIDIA" style="height: 60px;">
5+
<a href="https://networkx.github.io/">
6+
<img src="https://avatars.githubusercontent.com/u/388785?s=200&v=4" alt="NetworkX" style="height: 60px;">
7+
</a>
8+
<a href="https://www.arangodb.com/">
9+
<img src="https://arangodb.com/wp-content/uploads/2016/05/[email protected]" alt="ArangoDB" style="height: 60px;">
10+
</a>
11+
<a href="https://rapids.ai/">
12+
<img src="https://rapids.ai/images/RAPIDS-logo.png" alt="RAPIDS" style="height: 60px;">
13+
</a>
14+
<a href="https://www.nvidia.com/en-us/startups/">
15+
<img src="https://insights.virti.com/content/images/2021/09/20181218-Nvidia-Inception.png" alt="NVIDIA" style="height: 60px;">
16+
</a>
917
</div>
1018

1119
<br>
1220

13-
<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>
21+
<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>
1422
[![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)
1523
[![CodeQL](https://github.com/arangodb/nx-arangodb/actions/workflows/analyzee.yaml/badge.svg)](https://github.com/arangodb/nx-arangodb/actions/workflows/analyzee.yaml)
1624
[![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:
4452
6. Access to efficient distribution of graph data ([ArangoDB SmartGraphs](https://docs.arangodb.com/stable/graphs/smartgraphs/)).
4553

4654
<p align="center">
47-
<img src="./docs/_static/nxadb.png" style="height: 200px;">
55+
<img src="./doc/_static/nxadb.png" style="height: 200px;">
4856
</p>
4957

5058

@@ -169,7 +177,7 @@ nx.config.backends.arangodb.use_gpu = True
169177
```
170178

171179
<p align="center">
172-
<img src="./docs/_static/dispatch.png" style="height: 200px;">
180+
<img src="./doc/_static/dispatch.png" style="height: 200px;">
173181
</p>
174182

175183

‎docs/Makefile renamed to ‎doc/Makefile

File renamed without changes.

‎docs/_static/dispatch.png renamed to ‎doc/_static/dispatch.png

File renamed without changes.

‎docs/_static/nxadb.png renamed to ‎doc/_static/nxadb.png

File renamed without changes.

‎doc/algorithms/index.rst

+99
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
.. _algorithms:
2+
3+
**********
4+
Algorithms
5+
**********
6+
7+
As NetworkX-ArangoDB is primarily a **Storage Backend** to NetworkX, its primary focus is on persisting and reloading graphs from ArangoDB.
8+
9+
However, running algorithms on the graph is also still possible.
10+
11+
There are 3 ways to run algorithms on the graph:
12+
13+
1. **NetworkX**: The traditional way of running algorithms on Graphs.
14+
2. **NetworkX-cuGraph**: The GPU-accelerated way of running algorithms on Graphs.
15+
3. **ArangoDB**: The database way of running algorithms on Graphs.
16+
17+
Currently, Options 1 & 2 are supported, whereas Option 3 is a work-in-progress.
18+
19+
Running algorithms with Option 2 requires ``nx-cugraph`` to be installed on a system with a compatible GPU:
20+
21+
.. code-block::
22+
23+
pip install nx-cugraph-cu12 --extra-index-url https://pypi.nvidia.com
24+
25+
When running algorithms with Option 2, the graph is converted to a ``nx-cugraph`` graph, and the algorithm is run on the GPU.
26+
27+
This is only possible if ``nx-cugraph`` has implemented the algorithm you want to run.
28+
29+
- 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>`_.
30+
- For a list of algorithms that are supported by ``networkx``, refer to the `NetworkX Documentation <https://networkx.org/documentation/stable/reference/algorithms/index.html>`_.
31+
32+
``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.
33+
34+
You can also force-run algorithms on CPU even if ``nx-cugraph`` is installed:
35+
36+
.. code-block:: python
37+
38+
import os
39+
import networkx as nx
40+
import nx_arangodb as nxadb
41+
42+
# os.environ ...
43+
44+
G = nxadb.Graph(name="MyGraph")
45+
46+
nx.config.backends.arangodb.use_gpu = False
47+
48+
nx.pagerank(G)
49+
nx.betweenness_centrality(G)
50+
# ...
51+
52+
nx.config.backends.arangodb.use_gpu = True
53+
54+
55+
.. image:: ../_static/dispatch.png
56+
:align: center
57+
:alt: nx-arangodb dispatching
58+
:height: 200px
59+
60+
61+
**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.
62+
This is because we currently load the entire graph into memory before running *each* algorithm, which can be slow for large graphs.
63+
64+
.. code-block:: python
65+
66+
import networkx as nx
67+
import nx_arangodb as nxadb
68+
69+
G_adb = nxadb.Graph(name="MyGraph")
70+
71+
G_nx = nxadb.convert.nxadb_to_nx(G)
72+
73+
nx.pagerank(G_nx)
74+
nx.betweenness_centrality(G_nx)
75+
# ...
76+
77+
78+
**Option 3**
79+
80+
This is an experimental module seeking to provide server-side algorithms for `nx-arangodb` Graphs.
81+
The goal is to provide a set of algorithms that can be delegated to the server for processing,
82+
rather than having to pull all the data to the client and process it there.
83+
84+
Currently, the module is in a very early stage and only provides a single algorithm: `shortest_path`.
85+
This is simply to demonstrate the potential of the module and to provide a starting point for further development.
86+
87+
.. code-block:: python
88+
89+
import os
90+
import networkx as nx
91+
from nx_arangodb as nxadb
92+
93+
# os.environ ...
94+
95+
G = nxadb.Graph(name="MyGraph")
96+
97+
nx.pagerank(G) # Runs on the client
98+
nx.shortest_path(G, source="A", target="B") # Runs on the DB server
99+
nx.shortest_path.orig_func(G, source="A", target="B") # Runs on the client

‎doc/classes/digraph.rst

+89
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
.. _digraph:
2+
3+
=======
4+
DiGraph
5+
=======
6+
7+
Overview
8+
========
9+
.. currentmodule:: nx_arangodb
10+
.. autoclass:: DiGraph
11+
:members: query, chat
12+
13+
14+
Methods
15+
=======
16+
17+
Adding and removing nodes and edges
18+
-----------------------------------
19+
20+
.. autosummary::
21+
:toctree: generated/
22+
23+
DiGraph.__init__
24+
DiGraph.add_node
25+
DiGraph.add_nodes_from
26+
DiGraph.remove_node
27+
DiGraph.remove_nodes_from
28+
DiGraph.add_edge
29+
DiGraph.add_edges_from
30+
DiGraph.add_weighted_edges_from
31+
DiGraph.remove_edge
32+
DiGraph.remove_edges_from
33+
DiGraph.update
34+
DiGraph.clear
35+
DiGraph.clear_edges
36+
37+
38+
39+
Reporting nodes edges and neighbors
40+
-----------------------------------
41+
.. autosummary::
42+
:toctree: generated/
43+
44+
DiGraph.nodes
45+
DiGraph.__iter__
46+
DiGraph.has_node
47+
DiGraph.__contains__
48+
DiGraph.edges
49+
DiGraph.out_edges
50+
DiGraph.in_edges
51+
DiGraph.has_edge
52+
DiGraph.get_edge_data
53+
DiGraph.neighbors
54+
DiGraph.adj
55+
DiGraph.__getitem__
56+
DiGraph.successors
57+
DiGraph.succ
58+
DiGraph.predecessors
59+
DiGraph.pred
60+
DiGraph.adjacency
61+
DiGraph.nbunch_iter
62+
63+
64+
Counting nodes edges and neighbors
65+
----------------------------------
66+
.. autosummary::
67+
:toctree: generated/
68+
69+
DiGraph.order
70+
DiGraph.number_of_nodes
71+
DiGraph.__len__
72+
DiGraph.degree
73+
DiGraph.in_degree
74+
DiGraph.out_degree
75+
DiGraph.size
76+
DiGraph.number_of_edges
77+
78+
79+
Making copies and subgraphs
80+
---------------------------
81+
.. autosummary::
82+
:toctree: generated/
83+
84+
DiGraph.copy
85+
DiGraph.to_undirected
86+
DiGraph.to_directed
87+
DiGraph.subgraph
88+
DiGraph.edge_subgraph
89+
DiGraph.reverse

‎doc/classes/graph.rst

+81
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
.. _graph:
2+
3+
=====
4+
Graph
5+
=====
6+
7+
Overview
8+
========
9+
.. currentmodule:: nx_arangodb
10+
.. autoclass:: Graph
11+
:members: query, chat
12+
13+
14+
Methods
15+
=======
16+
17+
Adding and removing nodes and edges
18+
-----------------------------------
19+
20+
.. autosummary::
21+
:toctree: generated/
22+
23+
Graph.__init__
24+
Graph.add_node
25+
Graph.add_nodes_from
26+
Graph.remove_node
27+
Graph.remove_nodes_from
28+
Graph.add_edge
29+
Graph.add_edges_from
30+
Graph.add_weighted_edges_from
31+
Graph.remove_edge
32+
Graph.remove_edges_from
33+
Graph.update
34+
Graph.clear
35+
Graph.clear_edges
36+
37+
38+
39+
Reporting nodes edges and neighbors
40+
-----------------------------------
41+
.. autosummary::
42+
:toctree: generated/
43+
44+
Graph.nodes
45+
Graph.__iter__
46+
Graph.has_node
47+
Graph.__contains__
48+
Graph.edges
49+
Graph.has_edge
50+
Graph.get_edge_data
51+
Graph.neighbors
52+
Graph.adj
53+
Graph.__getitem__
54+
Graph.adjacency
55+
Graph.nbunch_iter
56+
57+
58+
59+
Counting nodes edges and neighbors
60+
----------------------------------
61+
.. autosummary::
62+
:toctree: generated/
63+
64+
Graph.order
65+
Graph.number_of_nodes
66+
Graph.__len__
67+
Graph.degree
68+
Graph.size
69+
Graph.number_of_edges
70+
71+
72+
Making copies and subgraphs
73+
---------------------------
74+
.. autosummary::
75+
:toctree: generated/
76+
77+
Graph.copy
78+
Graph.to_undirected
79+
Graph.to_directed
80+
Graph.subgraph
81+
Graph.edge_subgraph

0 commit comments

Comments
 (0)