diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml new file mode 100644 index 00000000..136a226b --- /dev/null +++ b/.github/workflows/deploy-docs.yml @@ -0,0 +1,34 @@ +name: Deploy-docs + +on: + push: + branches: [main] + pull_request: + +jobs: + build: + runs-on: ubuntu-latest + + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: "3.13" + + - name: Install deps + run: | + python3 -m pip install -U pip + python3 -m pip install -e ".[docs]" + + - name: Build docs (warnings as errors) + run: | + python3 -m sphinx -b html docs docs/_build/html + + - name: Upload HTML artifact + uses: actions/upload-artifact@v4 + with: + name: docs-html + path: docs/_build/html \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f90c9852..40195aed 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,4 @@ -# Welcome to nx-parallel! +# Contributors Guide Hi, Thanks for stopping by! @@ -105,7 +105,7 @@ git push origin For displaying a small note about nx-parallel's implementation at the end of the main NetworkX documentation, we use the `backend_info` [entry_point](https://packaging.python.org/en/latest/specifications/entry-points/#entry-points) (in the `pyproject.toml` file). The [`get_info` function](./_nx_parallel/__init__.py) is used to parse the docstrings of all the algorithms in nx-parallel and display the nx-parallel specific documentation on the NetworkX's main docs, in the "Additional Backend implementations" box, as shown in the screenshot below. -![backend_box_ss](./assets/images/backend_box_ss.png) +![backend_box_ss](_static/backend_box_ss.png) nx-parallel follows [sphinx docstring guidelines](https://the-ultimate-sphinx-tutorial.readthedocs.io/en/latest/_guide/_styleguides/docstrings-guidelines.html) for writing docstrings. But, while extracting the docstring to display on the main networkx docs, only the first paragraph of the function's description and the first paragraph of each parameter's description is extracted and displayed. So, make sure to include all the necessary information in the first paragraphs itself. And you only need to include the additional **backend** parameters in the `Parameters` section and not all the parameters. Also, it is recommended to include a link to the networkx function's documentation page in the docstring, at the end of the function description. diff --git a/README.md b/README.md index 8ed7910d..b02f1b4b 100644 --- a/README.md +++ b/README.md @@ -1,61 +1,7 @@ -# nx-parallel +# Overview nx-parallel is a NetworkX backend that uses joblib for parallelization. This project aims to provide parallelized implementations of various NetworkX functions to improve performance. Refer [NetworkX backends documentation](https://networkx.org/documentation/latest/reference/backends.html) to learn more about the backend architecture in NetworkX. -## Algorithms in nx-parallel - -- [adamic_adar_index](https://github.com/networkx/nx-parallel/blob/main/nx_parallel/algorithms/link_prediction.py#L108) -- [all_pairs_all_shortest_paths](https://github.com/networkx/nx-parallel/blob/main/nx_parallel/algorithms/shortest_paths/generic.py#L11) -- [all_pairs_bellman_ford_path](https://github.com/networkx/nx-parallel/blob/main/nx_parallel/algorithms/shortest_paths/weighted.py#L208) -- [all_pairs_bellman_ford_path_length](https://github.com/networkx/nx-parallel/blob/main/nx_parallel/algorithms/shortest_paths/weighted.py#L165) -- [all_pairs_dijkstra](https://github.com/networkx/nx-parallel/blob/main/nx_parallel/algorithms/shortest_paths/weighted.py#L29) -- [all_pairs_dijkstra_path](https://github.com/networkx/nx-parallel/blob/main/nx_parallel/algorithms/shortest_paths/weighted.py#L122) -- [all_pairs_dijkstra_path_length](https://github.com/networkx/nx-parallel/blob/main/nx_parallel/algorithms/shortest_paths/weighted.py#L72) -- [all_pairs_node_connectivity](https://github.com/networkx/nx-parallel/blob/main/nx_parallel/algorithms/connectivity/connectivity.py#L18) -- [all_pairs_shortest_path](https://github.com/networkx/nx-parallel/blob/main/nx_parallel/algorithms/shortest_paths/unweighted.py#L62) -- [all_pairs_shortest_path_length](https://github.com/networkx/nx-parallel/blob/main/nx_parallel/algorithms/shortest_paths/unweighted.py#L19) -- [approximate_all_pairs_node_connectivity](https://github.com/networkx/nx-parallel/blob/main/nx_parallel/algorithms/approximation/connectivity.py#L14) -- [average_clustering](https://github.com/networkx/nx-parallel/blob/main/nx_parallel/algorithms/cluster.py#L213) -- [average_neighbor_degree](https://github.com/networkx/nx-parallel/blob/main/nx_parallel/algorithms/assortativity/neighbor_degree.py#L10) -- [betweenness_centrality](https://github.com/networkx/nx-parallel/blob/main/nx_parallel/algorithms/centrality/betweenness.py#L20) -- [closeness_vitality](https://github.com/networkx/nx-parallel/blob/main/nx_parallel/algorithms/vitality.py#L10) -- [clustering](https://github.com/networkx/nx-parallel/blob/main/nx_parallel/algorithms/cluster.py#L146) -- [cn_soundarajan_hopcroft](https://github.com/networkx/nx-parallel/blob/main/nx_parallel/algorithms/link_prediction.py#L200) -- [colliders](https://github.com/networkx/nx-parallel/blob/main/nx_parallel/algorithms/dag.py#L37) -- [common_neighbor_centrality](https://github.com/networkx/nx-parallel/blob/main/nx_parallel/algorithms/link_prediction.py#L158) -- [edge_betweenness_centrality](https://github.com/networkx/nx-parallel/blob/main/nx_parallel/algorithms/centrality/betweenness.py#L103) -- [harmonic_centrality](https://github.com/networkx/nx-parallel/blob/main/nx_parallel/algorithms/centrality/harmonic.py#L10) -- [is_reachable](https://github.com/networkx/nx-parallel/blob/main/nx_parallel/algorithms/tournament.py#L15) -- [jaccard_coefficient](https://github.com/networkx/nx-parallel/blob/main/nx_parallel/algorithms/link_prediction.py#L80) -- [johnson](https://github.com/networkx/nx-parallel/blob/main/nx_parallel/algorithms/shortest_paths/weighted.py#L251) -- [local_efficiency](https://github.com/networkx/nx-parallel/blob/main/nx_parallel/algorithms/efficiency_measures.py#L11) -- [node_redundancy](https://github.com/networkx/nx-parallel/blob/main/nx_parallel/algorithms/bipartite/redundancy.py#L12) -- [number_attracting_components](https://github.com/networkx/nx-parallel/blob/main/nx_parallel/algorithms/components/attracting.py#L9) -- [number_connected_components](https://github.com/networkx/nx-parallel/blob/main/nx_parallel/algorithms/components/connected.py#L9) -- [number_of_isolates](https://github.com/networkx/nx-parallel/blob/main/nx_parallel/algorithms/isolate.py#L9) -- [number_strongly_connected_components](https://github.com/networkx/nx-parallel/blob/main/nx_parallel/algorithms/components/strongly_connected.py#L9) -- [number_weakly_connected_components](https://github.com/networkx/nx-parallel/blob/main/nx_parallel/algorithms/components/weakly_connected.py#L9) -- [preferential_attachment](https://github.com/networkx/nx-parallel/blob/main/nx_parallel/algorithms/link_prediction.py#L133) -- [ra_index_soundarajan_hopcroft](https://github.com/networkx/nx-parallel/blob/main/nx_parallel/algorithms/link_prediction.py#L232) -- [resource_allocation_index](https://github.com/networkx/nx-parallel/blob/main/nx_parallel/algorithms/link_prediction.py#L55) -- [square_clustering](https://github.com/networkx/nx-parallel/blob/main/nx_parallel/algorithms/cluster.py#L22) -- [tournament_is_strongly_connected](https://github.com/networkx/nx-parallel/blob/main/nx_parallel/algorithms/tournament.py#L76) -- [triangles](https://github.com/networkx/nx-parallel/blob/main/nx_parallel/algorithms/cluster.py#L84) -- [v_structures](https://github.com/networkx/nx-parallel/blob/main/nx_parallel/algorithms/dag.py#L13) -- [within_inter_cluster](https://github.com/networkx/nx-parallel/blob/main/nx_parallel/algorithms/link_prediction.py#L264) - -
-Script used to generate the above list - -``` -import _nx_parallel as nxp -d = nxp.get_funcs_info() # temporarily add `from .update_get_info import *` to _nx_parallel/__init__.py -for func in d: - print(f"- [{func}]({d[func]['url']})") -``` - -
- ## Installation You can install the stable version of nx-parallel using pip or conda: @@ -73,7 +19,7 @@ For more, see [INSTALL.md](./INSTALL.md). You can run your networkx code with nx-parallel backend by: ```sh -export NETWORKX_AUTOMATIC_BACKENDS="parallel" && python nx_code.py +export NETWORKX_BACKEND_PRIORITY="parallel" && python nx_code.py ``` Note that for all functions inside `nx_code.py` that do not have an nx-parallel implementation, their original networkx implementation will be executed. You can also use the nx-parallel backend in your code for only some specific function calls in the following ways: diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 120000 index 00000000..44fcc634 --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1 @@ +../CONTRIBUTING.md \ No newline at end of file diff --git a/docs/Config.md b/docs/Config.md new file mode 120000 index 00000000..b4c4f1a7 --- /dev/null +++ b/docs/Config.md @@ -0,0 +1 @@ +../Config.md \ No newline at end of file diff --git a/docs/INSTALL.md b/docs/INSTALL.md new file mode 120000 index 00000000..71db8b49 --- /dev/null +++ b/docs/INSTALL.md @@ -0,0 +1 @@ +../INSTALL.md \ No newline at end of file diff --git a/docs/LICENSE.md b/docs/LICENSE.md new file mode 120000 index 00000000..7eabdb1c --- /dev/null +++ b/docs/LICENSE.md @@ -0,0 +1 @@ +../LICENSE.md \ No newline at end of file diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..d4bb2cbb --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/Overview.md b/docs/Overview.md new file mode 120000 index 00000000..32d46ee8 --- /dev/null +++ b/docs/Overview.md @@ -0,0 +1 @@ +../README.md \ No newline at end of file diff --git a/docs/Tutorial.md b/docs/Tutorial.md new file mode 100644 index 00000000..d82954d8 --- /dev/null +++ b/docs/Tutorial.md @@ -0,0 +1,3 @@ +# Tutorial + +todo \ No newline at end of file diff --git a/assets/images/backend_box_ss.png b/docs/_static/backend_box_ss.png similarity index 100% rename from assets/images/backend_box_ss.png rename to docs/_static/backend_box_ss.png diff --git a/docs/_static/nx_parallel_banner.svg b/docs/_static/nx_parallel_banner.svg new file mode 100644 index 00000000..2b632ae9 --- /dev/null +++ b/docs/_static/nx_parallel_banner.svg @@ -0,0 +1,208 @@ + + + +nx-parallelParallel Network Analysis in Python diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 00000000..cd33f4dc --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,66 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = "nx-parallel" +copyright = "2026, nx-parallel contributors" +author = "Aditi Juneja" +release = "0.4" + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + "myst_parser", + "autoapi.extension", + "sphinx.ext.viewcode", + "sphinx.ext.intersphinx", + "sphinx.ext.autodoc", +] +source_suffix = {".rst": "restructuredtext", ".md": "markdown"} + +templates_path = ["_templates"] +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = "pydata_sphinx_theme" +html_logo = "_static/nx_parallel_banner.svg" +html_static_path = ["_static"] + +html_theme_options = { + "navbar_start": ["navbar-logo"], + "navbar_end": ["theme-switcher", "navbar-icon-links"], + "navbar_persistent": ["search-button"], + "secondary_sidebar_items": ["page-toc", "edit-this-page"], + "github_url": "https://github.com/networkx/nx-parallel/", +} + +autoapi_type = "python" +autoapi_dirs = ["../nx_parallel", "../_nx_parallel"] +autoapi_root = "api/" +autoapi_keep_files = False +autoapi_options = [ + "members", + "undoc-members", + "show-inheritance", + "show-module-summary", +] +autoapi_ignore = [ + "*tests*", + "*test_*", + "*/benchmarks/*", + "*/timing/*", +] + +intersphinx_mapping = { + "python": ("https://docs.python.org/3", None), + "networkx": ("https://networkx.org/documentation/stable/", None), + "nx-parallel": ("https://networkx.org/nx-parallel/", None), +} diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..b2b93756 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,24 @@ +Welcome to nx-parallel's documentation! +======================================= + +Hi! thanks for stopping by! + +License +------- + +```{include} LICENSE.md +``` + +```{toctree} +--- +maxdepth: 1 +hidden: true +--- + +Overview +INSTALL +api/index +Config +timing/index +CONTRIBUTING +``` \ No newline at end of file diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 00000000..954237b9 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/timing/index.md b/docs/timing/index.md new file mode 120000 index 00000000..2fed9018 --- /dev/null +++ b/docs/timing/index.md @@ -0,0 +1 @@ +../../timing/README.md \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index aa298eb3..0d87feee 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -60,7 +60,13 @@ test = [ 'numpy>=2', 'scipy>=1.12', ] - +docs = [ + 'sphinx>=8', + 'pydata-sphinx-theme>=0.15', + 'myst-parser>=2', + 'sphinx-autoapi>=3', + 'intersphinx_registry', +] [tool.pytest.ini_options] filterwarnings = [ # note the use of single quote below to denote "raw" strings in TOML