diff --git a/Makefile b/Makefile index 948180ad..f93e099e 100644 --- a/Makefile +++ b/Makefile @@ -13,18 +13,19 @@ venv: clean-venv clean-venv: rm -rf $(VENV) -.PHONY: install-reqs -install-reqs: - pip install --upgrade pip +.PHONY: install +install: + @$(PYTHON3) -m pip install --upgrade pip + @$(PYTHON3) -m pip install -e . @$(PYTHON3) -m pip install -r requirements.txt - pip install pytest pytest-cov decorator ## Environment using Poetry .PHONY: develop develop: clean-poetry-env - poetry install --all-extras --with test poetry shell + poetry install --with test + .PHONY: requirements.txt requirements.txt: diff --git a/README.md b/README.md index 9fd7abc0..1f0728a5 100644 --- a/README.md +++ b/README.md @@ -190,29 +190,71 @@ 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 + +# Create a virtual environment make venv source venv-hnx/bin/activate -pip install . + +# install required dependencies +make install ``` Development =========== Install an editable version ---------------------------- - ``` pip install -e . ``` -Install an editable version with supported applications -------------------------------------------------------- +Install additional dependencies to support testing and jupyter notebooks: +``` +pip install -r requirements.txt +``` -```shell -pip install -e .['all'] +You can also install all these requirements in one Make target: + +``` +make install +``` + +Poetry +====== -# for zsh users -pip install -e .'[all]' +This library uses [Poetry](https://python-poetry.org/docs/) to manage dependencies and packaging. Poetry can also be +used to manage your environment for development. + +Prerequisites +------------- + +* [Install Poetry](https://python-poetry.org/docs/#installation) + + +Configure Poetry +---------------- + +[Configure your Poetry](https://python-poetry.org/docs/configuration/) to create the virtual environment in your project directory: +``` +poetry config virtualenvs.in-project true + +# check the poetry configuration +poetry config --list +``` + +Set up virtual environment +---------------------------- + +Create and activate a virtual environment. +``` +poetry shell +``` + +NOTE: If you plan to use Poetry to manage your virtual environment, you can activate the virtual environment +using poerty: `poetry shell`. Another option is to directly + +Install required dependencies and HyperNetX in editable mode. +``` +poetry install ``` Install support for testing @@ -221,7 +263,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 -make test-deps +poetry install --with test # run tests python -m pytest @@ -237,17 +279,13 @@ open htmlcov/index.html Install support for tutorials ----------------------------- -``` shell -make tutorial-deps +``` +poetry install --with tutorials # open Jupyter notebooks in a browser make tutorials ``` - - - - Code Quality ------------ HyperNetX uses a number of tools to maintain code quality: @@ -257,12 +295,12 @@ HyperNetX uses a number of tools to maintain code quality: Before using these tools, ensure that you install Pylint in your environment: -```shell -make lint-deps +``` +poetry install --with lint ``` - -### Pylint +Pylint +------ [Pylint](https://pylint.pycqa.org/en/latest/index.html) is a static code analyzer for Python-based projects. From the [Pylint docs](https://pylint.pycqa.org/en/latest/index.html#what-is-pylint): @@ -282,37 +320,31 @@ pylint hypernetx --output=pylint-results.txt For more information on configuration, see https://pylint.pycqa.org/en/latest/user_guide/configuration/index.html -### Black - +Black +----- [Black](https://black.readthedocs.io/en/stable/) is a PEP 8 compliant formatter for Python-based project. This tool is highly opinionated about how Python should be formatted and will automagically reformat your code. ```shell -make format-deps black hypernetx ``` Documentation -=============== +------------- -Build and view documentation locally ---------------------------- +Build and view documentation locally: ``` -make docs-deps +poetry install --with docs cd docs make html open docs/build/html/index.html ``` -Editing documentation ----------------------- - 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 ``` @@ -353,7 +385,7 @@ gh run list --workflow=ci.yml --repo pnnl/HyperNetX Versioning ----------- +========== This project uses [`commitizen`](https://github.com/commitizen-tools/commitizen) to manage versioning. The files where "version" will be updated are listed in the '.cz.toml' file. To create a new version and the associated tag, @@ -361,7 +393,7 @@ run the following commands: ```shell # Install commitizen tool to environment -make version-deps +pip install commitizen # Updates version; values for '--increment' can be MAJOR, MINOR, or PATCH # Autocreates a tag and commit for the updated version diff --git a/docs/source/install.rst b/docs/source/install.rst index eb59e085..22948b33 100644 --- a/docs/source/install.rst +++ b/docs/source/install.rst @@ -2,10 +2,6 @@ Installing HyperNetX ******************** - -Installation -############ - The recommended installation method for most users is to create a virtual environment and install HyperNetX from PyPi. @@ -56,13 +52,13 @@ To deactivate your environment, use: >>> .\env-hnx\Scripts\deactivate -Installing Hypernetx -#################### +Installation +############ Regardless of how you install HyperNetX, ensure that your environment is activated and that you are running Python >=3.8. Installing from PyPi -************************* +******************** >>> pip install hypernetx @@ -70,14 +66,10 @@ If you want to use supported applications built upon HyperNetX (e.g. ``hypernetx ``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]' + >>> pip install igraph celluloid Installing from Source -************************* +********************** Ensure that you have ``git`` installed. @@ -85,14 +77,14 @@ Ensure that you have ``git`` installed. >>> cd HyperNetX >>> make venv >>> source venv-hnx/bin/activate - >>> pip install . + >>> make install Post-Installation Actions -########################## +######################### Interact with HyperNetX in a REPL -******************************************** +********************************* Ensure that your environment is activated and that you run ``python`` on your terminal to open a REPL: @@ -108,7 +100,7 @@ Ensure that your environment is activated and that you run ``python`` on your te Other Actions if installed from source -******************************************** +************************************** If you have installed HyperNetX from source, you can perform additional actions such as viewing the provided Jupyter notebooks or building the documentation locally. @@ -121,7 +113,6 @@ Viewing jupyter notebooks The following command will automatically open the notebooks in a browser. - >>> make tutorial-deps >>> make tutorials @@ -130,9 +121,7 @@ Building documentation The following commands will build and open a local version of the documentation in a browser: - >>> make docs-deps + >>> pip install sphinx sphinx-autobuild sphinx-rtd-theme sphinx-copybutton >>> cd docs >>> make html >>> open build/index.html - - diff --git a/poetry.lock b/poetry.lock index c073d1d7..cf135d67 100644 --- a/poetry.lock +++ b/poetry.lock @@ -2288,19 +2288,19 @@ webpdf = ["playwright"] [[package]] name = "nbformat" -version = "5.10.3" +version = "5.10.4" description = "The Jupyter Notebook format" optional = false python-versions = ">=3.8" files = [ - {file = "nbformat-5.10.3-py3-none-any.whl", hash = "sha256:d9476ca28676799af85385f409b49d95e199951477a159a576ef2a675151e5e8"}, - {file = "nbformat-5.10.3.tar.gz", hash = "sha256:60ed5e910ef7c6264b87d644f276b1b49e24011930deef54605188ddeb211685"}, + {file = "nbformat-5.10.4-py3-none-any.whl", hash = "sha256:3b48d6c8fbca4b299bf3982ea7db1af21580e4fec269ad087b9e81588891200b"}, + {file = "nbformat-5.10.4.tar.gz", hash = "sha256:322168b14f937a5d11362988ecac2a4952d3d8e3a2cbeb2319584631226d5b3a"}, ] [package.dependencies] -fastjsonschema = "*" +fastjsonschema = ">=2.15" jsonschema = ">=2.6" -jupyter-core = "*" +jupyter-core = ">=4.12,<5.0.dev0 || >=5.1.dev0" traitlets = ">=5.1" [package.extras] @@ -4207,4 +4207,4 @@ testing = ["big-O", "jaraco.functools", "jaraco.itertools", "more-itertools", "p [metadata] lock-version = "2.0" python-versions = "^3.8,<3.12" -content-hash = "11fe02013b7eb7c65015cf919d0f77d59e6870d712864b8b78beece9500979a0" +content-hash = "9392fa3e0d0dffb6d433bea34665f08b4d2d15bf5268138c9afff2875ccb98fb" diff --git a/pyproject.toml b/pyproject.toml index ffce6f3c..7b0f1ab3 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -26,9 +26,11 @@ python = "^3.8,<3.12" networkx = "^2.2" pandas = "^1.5.3" scikit-learn = "^1.3.2" + +[tool.poetry.group.algorithms.dependencies] +decorator = "^5.1.1" celluloid = "^0.2.0" igraph = "^0.11.4" -decorator = "^5.1.1" [tool.poetry.group.widget] optional = true diff --git a/requirements.txt b/requirements.txt index 5af3b014..f9d716f9 100644 --- a/requirements.txt +++ b/requirements.txt @@ -35,6 +35,7 @@ h11==0.14.0 hnxwidget==0.1.1b3 httpcore==1.0.5 httpx==0.27.0 +-e git+ssh://git@stash.pnnl.gov:7999/hyp/hypernetx.git@70360f14748f8f66188a04179d741201452e389a#egg=hypernetx idna==3.6 igraph==0.11.4 iniconfig==2.0.0 @@ -74,7 +75,7 @@ matplotlib-inline==0.1.6 mistune==3.0.2 nbclient==0.6.8 nbconvert==7.16.3 -nbformat==5.10.3 +nbformat==5.10.4 nbmake==1.5.3 nest-asyncio==1.6.0 networkx==2.8.8