From 43d35dea965aba7e3ccc187803cfaced50cb22f1 Mon Sep 17 00:00:00 2001 From: Mark Bonicillo Date: Fri, 1 Mar 2024 11:36:05 -0800 Subject: [PATCH] Update docs on installation, widget; update Readme and Makefile --- Makefile | 16 ++++---- README.md | 45 +++++++++------------ docs/source/classes/classes.rst | 8 ---- docs/source/install.rst | 69 +++++++++++++-------------------- docs/source/widget.rst | 20 +++++----- setup.cfg | 1 - 6 files changed, 64 insertions(+), 95 deletions(-) diff --git a/Makefile b/Makefile index 814ca3e3..42b60458 100644 --- a/Makefile +++ b/Makefile @@ -56,7 +56,7 @@ test-ci-github: lint-deps lint pre-commit ci-github-deps test-deps test-ci .PHONY: publish-deps publish-deps: - @$(PYTHON3) -m pip install -e .'[packaging]' --use-pep517 + @$(PYTHON3) -m pip install -e .[packaging] --use-pep517 .PHONY: build-dist build-dist: publish-deps clean @@ -75,21 +75,21 @@ publish-to-pypi: publish-deps build-dist .PHONY: version-deps version-deps: - @$(PYTHON3) -m pip install .'[releases]' --use-pep517 + @$(PYTHON3) -m pip install .[releases] --use-pep517 ### Documentation .PHONY: docs-deps docs-deps: - @$(PYTHON3) -m pip install .'[documentation]' --use-pep517 + @$(PYTHON3) -m pip install .[documentation] --use-pep517 ## Tutorials .PHONY: tutorial-deps tutorial-deps: - @$(PYTHON3) -m pip install .'[tutorials]' .'[widget]' --use-pep517 + @$(PYTHON3) -m pip install .[tutorials] .[widget] --use-pep517 .PHONY: tutorials tutorials: @@ -116,16 +116,16 @@ ci-github-deps: .PHONY: lint-deps lint-deps: - @$(PYTHON3) -m pip install .'[lint]' --use-pep517 + @$(PYTHON3) -m pip install .[lint] --use-pep517 .PHONY: format-deps format-deps: - @$(PYTHON3) -m pip install .'[format]' --use-pep517 + @$(PYTHON3) -m pip install .[format] --use-pep517 .PHONY: test-deps test-deps: - @$(PYTHON3) -m pip install .'[testing]' --use-pep517 + @$(PYTHON3) -m pip install .[testing] --use-pep517 .PHONY: all-deps all-deps: - @$(PYTHON3) -m pip install .'[all]' --use-pep517 + @$(PYTHON3) -m pip install .[all] --use-pep517 diff --git a/README.md b/README.md index 26175364..344a942c 100644 --- a/README.md +++ b/README.md @@ -150,8 +150,8 @@ conda activate venv-hnx ```shell -virtualenv env-hnx -source env-hnx/bin/activate +virtualenv venv-hnx +source venv-hnx/bin/activate ``` @@ -190,19 +190,11 @@ Ensure that you have [git](https://git-scm.com/book/en/v2/Getting-Started-Instal ```shell git clone https://github.com/pnnl/HyperNetX.git cd HyperNetX +make venv +source venv-hnx/bin/activate pip install . ``` -Post-Installation Actions -========================= - -Running Tests -------------- - -```shell -python -m pytest -``` - Development =========== @@ -213,10 +205,13 @@ Install an editable version pip install -e . ``` -Install an editable version with access to jupyter notebooks ------------------------------------------------------------- +Install an editable version with supported applications +------------------------------------------------------- ```shell +pip install -e .['all'] + +# for zsh users pip install -e .'[all]' ``` @@ -226,7 +221,7 @@ Install support for testing > ℹ️ **NOTE:** This project has a pytest configuration file named 'pytest.ini'. By default, pytest will use those configuration settings to run tests. ```shell -pip install .'[testing]' +make test-deps # run tests python -m pytest @@ -243,20 +238,14 @@ Install support for tutorials ----------------------------- ``` shell -pip install .'[tutorials]' +make tutorial-deps + +# open Jupyter notebooks in a browser +make tutorials ``` -Install support for documentation ---------------------------------- -```shell -pip install .'[documentation]' -cd docs -## This will generate the documentation in /docs/build/ -## Open them in your browser with docs/build/html/index.html -make html -``` Code Quality @@ -269,7 +258,7 @@ HyperNetX uses a number of tools to maintain code quality: Before using these tools, ensure that you install Pylint in your environment: ```shell -pip install .'[lint]' +make lint-deps ``` @@ -299,6 +288,7 @@ For more information on configuration, see https://pylint.pycqa.org/en/latest/us ```shell +make format-deps black hypernetx ``` @@ -309,6 +299,7 @@ Build and view documentation locally --------------------------- ``` +make docs-deps cd docs make html open docs/build/html/index.html @@ -316,12 +307,12 @@ open docs/build/html/index.html Editing documentation ---------------------- -NOTE: make sure you install the required dependencies using: `make docs-deps` When editing documentation, you can auto-rebuild the documentation locally so that you can view your document changes live on the browser without having to rebuild every time you have a change. ``` +make docs-deps cd docs make livehtml ``` diff --git a/docs/source/classes/classes.rst b/docs/source/classes/classes.rst index 75542ea7..f6e8cb3f 100644 --- a/docs/source/classes/classes.rst +++ b/docs/source/classes/classes.rst @@ -4,14 +4,6 @@ classes package Submodules ---------- -classes.entity module ---------------------- - -.. automodule:: classes.entity - :members: - :undoc-members: - :show-inheritance: - classes.entityset module ------------------------ diff --git a/docs/source/install.rst b/docs/source/install.rst index 4ce55380..eb59e085 100644 --- a/docs/source/install.rst +++ b/docs/source/install.rst @@ -26,21 +26,21 @@ Create a virtual environment Using Anaconda ************************* - >>> conda create -n env-hnx python=3.8 -y - >>> conda activate env-hnx + >>> conda create -n venv-hnx python=3.8 -y + >>> conda activate venv-hnx Using venv ************************* >>> python -m venv venv-hnx - >>> source env-hnx/bin/activate + >>> source venv-hnx/bin/activate Using virtualenv ************************* - >>> virtualenv env-hnx - >>> source env-hnx/bin/activate + >>> virtualenv venv-hnx + >>> source venv-hnx/bin/activate For Windows Users @@ -66,6 +66,15 @@ Installing from PyPi >>> pip install hypernetx +If you want to use supported applications built upon HyperNetX (e.g. ``hypernetx.algorithms.hypergraph_modularity`` or +``hypernetx.algorithms.contagion``), you can install HyperNetX with those supported applications by using +the following command: + + >>> pip install hypernetx[all] + +If you are using zsh as your shell, use single quotation marks around the square brackets: + + >>> pip install hypernetx'[all]' Installing from Source ************************* @@ -74,43 +83,14 @@ Ensure that you have ``git`` installed. >>> git clone https://github.com/pnnl/HyperNetX.git >>> cd HyperNetX - >>> pip install -e .['all'] - -If you are using zsh as your shell, ensure that the single quotation marks are placed outside the square brackets: - - >>> pip install -e .'[all]' + >>> make venv + >>> source venv-hnx/bin/activate + >>> pip install . Post-Installation Actions ########################## -Running Tests -************** - -To run all the tests, ensure that you first install the testing dependencies: - - >>> pip install -e .['testing'] - -Then try running all the tests: - - >>> python -m pytest - - -Dependencies for some Submodules -******************************** - -Two submodules in the library, ``hypernetx.algorithms.hypergraph_modularity`` and ``hypernetx.algorithms.contagion``, -require some additional dependencies. If you want to use those submodules, you will need to install those dependencies. - -For ``hypernetx.algorithms.hypergraph_modularity``, install the following: - - >>> pip install 'igraph>=0.10.4' - -For ``hypernetx.algorithms.contagion``, install the following: - - >>> pip install 'celluloid>=0.2.0' - - Interact with HyperNetX in a REPL ******************************************** @@ -130,14 +110,19 @@ Ensure that your environment is activated and that you run ``python`` on your te Other Actions if installed from source ******************************************** -Ensure that you are at the root of the source directory before running any of the following commands: +If you have installed HyperNetX from source, you can perform additional actions such as viewing the provided Jupyter notebooks +or building the documentation locally. + +Ensure that you have activated your virtual environment and are at the root of the source directory before running any of the following commands: + Viewing jupyter notebooks -------------------------- The following command will automatically open the notebooks in a browser. - >>> jupyter-notebook tutorials + >>> make tutorial-deps + >>> make tutorials Building documentation @@ -145,7 +130,9 @@ Building documentation The following commands will build and open a local version of the documentation in a browser: - >>> make build-docs - >>> open docs/build/index.html + >>> make docs-deps + >>> cd docs + >>> make html + >>> open build/index.html diff --git a/docs/source/widget.rst b/docs/source/widget.rst index 5805827a..4d0c2e6f 100644 --- a/docs/source/widget.rst +++ b/docs/source/widget.rst @@ -30,10 +30,16 @@ HyperNetXWidget is currently in beta and will only work on Jupyter Notebook 6.5. but support for Jupyter Lab is in planning. In addition, HyperNetXWidget must be installed using the `Anaconda platform `_ so that the -widget can render on Jupyter notebook. It is highly recommended to use the base environment provided by Anaconda because -Anaconda's package management system, `conda`, will resolve dependencies when HyperNetX and HyperNetXWidget are -installed. For more information on `conda` environments, please see `their documentation here. -`_ +widget can render on Jupyter notebook. + +For users with inexperience with Jupyter and Anaconda, it is highly recommended to use the base environment of Anaconda so +that the widget works seamlessly and out-of-the box on Jupyter Notebook. The widget does not work on Jupyter Lab. + +If users want to create a custom environment instead of using the base environment provided by Anaconda, then users +will need to do additional configuration on Jupyter and the kernel to ensure that the widget works. +Specifically, users will need to set the Kernel to use a custom environment. For a guide on how to do this, please +read and follow this guide: `How to add your Conda environment to your jupyter notebook in just 4 steps `_. + **Do not use python's built-in venv module or virtualenv to create a virtual environment; the widget will not render on Jupyter notebook.** @@ -91,12 +97,6 @@ following screenshot as an example: :align: center -| -| For more information on setting the environment in Jupyter notebook, see - `How to add your Conda environment to your jupyter notebook in just 4 steps. - `_ - - Using the Tool -------------- diff --git a/setup.cfg b/setup.cfg index 5aab39d7..30c3b1f1 100644 --- a/setup.cfg +++ b/setup.cfg @@ -103,7 +103,6 @@ documentation = sphinx-rtd-theme>=1.2.1 sphinx-autobuild>=2021.3.14 sphinx-copybutton>=0.5.1 - nb2plots>=0.6.1 packaging = build>=0.10.0 twine>=4.0.2