From 70cd058671a3a99235e446aa737409552e4d4675 Mon Sep 17 00:00:00 2001 From: Aditi Juneja <1509aditi@gmail.com> Date: Fri, 20 Mar 2026 02:58:58 +0530 Subject: [PATCH 1/2] setting up sphinx website --- .github/workflows/deploy-docs.yml | 34 ++++++++++++++++++ CONTRIBUTING.md | 2 +- README.md | 56 +----------------------------- docs/CONTRIBUTING.md | 1 + docs/Config.md | 1 + docs/INSTALL.md | 1 + docs/Makefile | 20 +++++++++++ docs/Overview.md | 1 + docs/Tutorial.md | 1 + docs/conf.py | 57 +++++++++++++++++++++++++++++++ docs/index.md | 19 +++++++++++ docs/make.bat | 35 +++++++++++++++++++ docs/timing/index.md | 1 + pyproject.toml | 7 +++- 14 files changed, 179 insertions(+), 57 deletions(-) create mode 100644 .github/workflows/deploy-docs.yml create mode 120000 docs/CONTRIBUTING.md create mode 120000 docs/Config.md create mode 120000 docs/INSTALL.md create mode 100644 docs/Makefile create mode 120000 docs/Overview.md create mode 100644 docs/Tutorial.md create mode 100644 docs/conf.py create mode 100644 docs/index.md create mode 100644 docs/make.bat create mode 120000 docs/timing/index.md 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..c6e8da8f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,4 @@ -# Welcome to nx-parallel! +# Contributors Guide Hi, Thanks for stopping by! diff --git a/README.md b/README.md index 8ed7910d..dde7823f 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: 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/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..45d93580 --- /dev/null +++ b/docs/Tutorial.md @@ -0,0 +1 @@ +# ToDo \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 00000000..1aa399dc --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,57 @@ +# 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", +] +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_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"], +} + +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/*", +] diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..a56806c9 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,19 @@ +Welcome to nx-parallel's documentation! +======================================= + +Hi! thanks for stopping by! + +```{toctree} +--- +maxdepth: 1 +hidden: true +--- + +Overview +INSTALL +Tutorial +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..ba43b70a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -60,7 +60,12 @@ test = [ 'numpy>=2', 'scipy>=1.12', ] - +docs = [ + 'sphinx>=8', + 'pydata-sphinx-theme>=0.15', + 'myst-parser>=2', + 'sphinx-autoapi>=3', +] [tool.pytest.ini_options] filterwarnings = [ # note the use of single quote below to denote "raw" strings in TOML From 291384ba1bdf4f6ba8de3d5a1cb356ae1eb4ddde Mon Sep 17 00:00:00 2001 From: Aditi Juneja <1509aditi@gmail.com> Date: Wed, 8 Apr 2026 17:31:24 +0530 Subject: [PATCH 2/2] added license, logo; rm tutorial; updated env var in readme; added intersphinx_mapping --- CONTRIBUTING.md | 2 +- README.md | 2 +- docs/LICENSE.md | 1 + docs/Tutorial.md | 4 +- .../_static}/backend_box_ss.png | Bin docs/_static/nx_parallel_banner.svg | 208 ++++++++++++++++++ docs/conf.py | 9 + docs/index.md | 7 +- pyproject.toml | 1 + 9 files changed, 230 insertions(+), 4 deletions(-) create mode 120000 docs/LICENSE.md rename {assets/images => docs/_static}/backend_box_ss.png (100%) create mode 100644 docs/_static/nx_parallel_banner.svg diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c6e8da8f..40195aed 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 dde7823f..b02f1b4b 100644 --- a/README.md +++ b/README.md @@ -19,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/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/Tutorial.md b/docs/Tutorial.md index 45d93580..d82954d8 100644 --- a/docs/Tutorial.md +++ b/docs/Tutorial.md @@ -1 +1,3 @@ -# ToDo \ No newline at end of file +# 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 index 1aa399dc..cd33f4dc 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -19,6 +19,7 @@ "autoapi.extension", "sphinx.ext.viewcode", "sphinx.ext.intersphinx", + "sphinx.ext.autodoc", ] source_suffix = {".rst": "restructuredtext", ".md": "markdown"} @@ -30,6 +31,7 @@ # 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 = { @@ -37,6 +39,7 @@ "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" @@ -55,3 +58,9 @@ "*/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 index a56806c9..b2b93756 100644 --- a/docs/index.md +++ b/docs/index.md @@ -3,6 +3,12 @@ Welcome to nx-parallel's documentation! Hi! thanks for stopping by! +License +------- + +```{include} LICENSE.md +``` + ```{toctree} --- maxdepth: 1 @@ -11,7 +17,6 @@ hidden: true Overview INSTALL -Tutorial api/index Config timing/index diff --git a/pyproject.toml b/pyproject.toml index ba43b70a..0d87feee 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -65,6 +65,7 @@ docs = [ 'pydata-sphinx-theme>=0.15', 'myst-parser>=2', 'sphinx-autoapi>=3', + 'intersphinx_registry', ] [tool.pytest.ini_options] filterwarnings = [