From 036f05c29648f8de27c94751bfb78b702bdfe77c Mon Sep 17 00:00:00 2001 From: Ludovico Bianchi Date: Thu, 25 Apr 2024 12:48:17 -0500 Subject: [PATCH 1/5] Apply formatting fixes --- README-developer.md | 18 +++++++++++++----- README.md | 12 +++++------- 2 files changed, 18 insertions(+), 12 deletions(-) diff --git a/README-developer.md b/README-developer.md index e46b2472..6d18fc1a 100644 --- a/README-developer.md +++ b/README-developer.md @@ -303,7 +303,8 @@ The output will be in `_dev/notebooks/_build/html`. In addition to per-cell tags, the preprocessor also can look at notebook-level metadata. This is currently used for only one purpose: to tell the preprocessor not to generate a 'test' notebook, and thereby to skip the given notebook in the tests. In order to make this happen, either manually edit the notebook source or use the Jupyter notebook "Edit -> Edit Notebook Metadata" menu item to add the following section to the notebook-level metadata: -``` + +```json "idaes": { "skip": ["test"] } @@ -329,16 +330,19 @@ Instructions to package and distribute the examples as idaes-examples in PyPI. Based on the PyPA [packaging projects](https://packaging.python.org/en/latest/tutorials/packaging-projects/) documentation. Install dependencies for packaging into your current (virtual) Python environment: + ```shell -pip install -e .[dev,jb,pkg] +pip install -e .[dev,packaging] ``` Edit the `pyproject.toml` file: - 1. Ensure that you have commented out the line under `[project.optional-dependencies]`, in the `dev` section, + +1. Ensure that you have commented out the line under `[project.optional-dependencies]`, in the `dev` section, that reads `"idaes-pse @ git+https://github.com/IDAES/idaes-pse"`. - 2. Set the release version. You should increment the version for each new release. +2. Set the release version. You should increment the version for each new release. **Build** the distribution: + ```shell > python -m build # Many lines of output later, you should see a message like: @@ -352,6 +356,7 @@ To generate an API token, go to _Settings_ → _API Tokens_, and selecting _A You will paste this token in the commands below. **Upload** to [TestPyPI](https://packaging.python.org/en/latest/guides/using-testpypi/): + ```shell > python -m twine upload --repository testpypi dist/* Uploading distributions to https://test.pypi.org/legacy/ @@ -360,17 +365,20 @@ Enter your password: {{paste token here}} ``` Create a new virtual environment and install the package from test.pypi into it: + ```shell pip install --extra-index-url https://test.pypi.org/simple/ idaes-examples ``` If the installation succeeds, you should be able to serve the notebooks: + ```shell idaesx serve ``` If it all looks good, you can repeat the **Upload** step with the real [PyPI](pypi.org) (you will need to get an account and token, just as for test.pypi.org, above): + ```shell > python -m twine upload dist/* Uploading distributions to https://upload.pypi.org/legacy/ @@ -388,4 +396,4 @@ Enter your password: {{past token here}} ---- Author: Dan Gunter -Last modified: 13 Mar 2023 +Last modified: 25 Apr 2024 diff --git a/README.md b/README.md index 3b2d4e05..7c3fafd9 100644 --- a/README.md +++ b/README.md @@ -18,8 +18,8 @@ Below are basic instructions to install, view, and run the examples. In the source code repository, you may note that there are a number of examples that are not in the documentation. There are two main categories of examples: - - "Docs" examples (under `idaes_examples/notebooks/docs`), which are tested and built into this documentation. - - "Active" examples (under `idaes_examples/notebooks/active`) that are tested but *not* in the documentation. +- "Docs" examples (under `idaes_examples/notebooks/docs`), which are tested and built into this documentation. +- "Active" examples (under `idaes_examples/notebooks/active`) that are tested but *not* in the documentation. There is also a third category of "Held" examples (under `idaes_examples/notebooks/held`), which could in the next release of IDAES in Docs or Active, or could be removed. @@ -41,7 +41,7 @@ to install and run the notebooks in an isolated environment. ## Run examples -Use the command +Use the command ``` idaesx serve ``` @@ -51,7 +51,7 @@ Alternately, you may use Jupyter notebook's file browser in the installed notebo using the `idaesx where` command to find that directory: `jupyter notebook $(idaesx where)`. -Only the source notebooks (ending in '_src.ipynb') are included in the repository. +Only the source notebooks (ending in `_src.ipynb`) are included in the repository. The `idaesx serve` command will generate the other versions, or you can run preprocessing manually with: `idaesx pre -d "$(idaesx where)\.."`. ## Build documentation @@ -59,11 +59,9 @@ The `idaesx serve` command will generate the other versions, or you can run prep Run the command `idaesx build` from the repository root to build the [JupyterBook](https://jupyterbook.org) documentation. - *Note: This will take quite a while, as each example must be run first. You may want to step out and enjoy a beverage.* - ---- Author: Dan Gunter -Last modified: 17 Feb 2023 +Last modified: 25 Apr 2024 From 0e75ff664c909e0ae45800e04e4e7223ec253f2b Mon Sep 17 00:00:00 2001 From: Ludovico Bianchi Date: Thu, 25 Apr 2024 12:48:42 -0500 Subject: [PATCH 2/5] Update installation instructions --- README.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 7c3fafd9..2050a9c7 100644 --- a/README.md +++ b/README.md @@ -30,9 +30,15 @@ These are *not* tested and *not* in the docs, and should generally be ignored by This repository can be installed with *pip*: ```shell -# RECOMMENDED: this will install the IDEAS examples, accessory code, -# plus the Graphical User Interface (GUI) to browse them (see section below) -pip install "idaes-examples[gui]" +# install the IDAES examples with a core set of dependencies +pip install idaes-examples + +# install the IDAES examples with additional dependencies needed to run specific examples, +# e.g. `omlt` for surrogate modeling with OMLT +pip install "idaes-examples[omlt]" + +# install the IDAES examples with dependencies need to build the documentation +pip install "idaes-examples[docs]" ``` We recommend you use a virtual environment tool such as From 123eb715eff1d4f6f64c542a6f27fe2c5b2804bf Mon Sep 17 00:00:00 2001 From: Ludovico Bianchi Date: Thu, 25 Apr 2024 12:49:14 -0500 Subject: [PATCH 3/5] Streamline pytest instructions --- README-developer.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/README-developer.md b/README-developer.md index 6d18fc1a..f3ddfe2a 100644 --- a/README-developer.md +++ b/README-developer.md @@ -82,13 +82,15 @@ Which one you run depends in which directory you run tests. If your current directory is the root of the repository: -1. `pytest .`: Runs **Python test modules**, matching the usual patterns (e.g., `*_test.py`). +1. `pytest .`: Runs **Python test modules**, matching the usual patterns (e.g., `test_*.py`). 2. `pytest idaes_examples`: Runs **Jupyter notebook tests.** Due to the presence of a special `conftest.py` file in this directory, Jupyter Notebooks will be preprocessed and then all test notebooks (their filename ending in `_test.ipynb`) will be executed. -### Integration tests +The `-v` or `--verbose` flag can be added to any pytest command so that more information is displayed while the test suite runs. -Run integration tests from the top-level (root) directory of the repository. -In the root directory, tests are configured by `pyproject.toml`; see the *tool.pytest.ini_options* section. +### Testing the notebooks + +To run all registered notebooks, run the following command from the top-level (root) directory of the repository, specifying `idaes_examples` as an argument. +The `pytest.ini` file and `conftest.py` files contained in `idaes_examples` will override the top-level pytest configuration defined in `pyproject.toml` under `[tool.pytest.ini_options]`. ```shell # from the root directory of the repository @@ -99,8 +101,7 @@ pytest idaes_examples To test just one notebook, you need to use the name of the *test* notebook not the source. For example, to test the `compressor.ipynb` notebook (in the `unit_models/operations` subdirectory) -you need to add `-c` and the path to the top-level *pyproject.toml*, which has the pytest configuration, -then use the name of the test notebook: +you need to use the name of the test notebook: ```shell pytest -v idaes_examples/notebooks/docs/unit_models/operations/compressor_test.ipynb From c3764413c5f78d5208c8895da069fa589877bf58 Mon Sep 17 00:00:00 2001 From: Ludovico Bianchi Date: Thu, 2 May 2024 18:14:25 -0500 Subject: [PATCH 4/5] Fix syntax on Win in conda create command spotted by @JavalVyas2000 --- README-developer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README-developer.md b/README-developer.md index f3ddfe2a..f2d4f4b4 100644 --- a/README-developer.md +++ b/README-developer.md @@ -37,7 +37,7 @@ Clone the repository from GitHub, set up your Python environment as you usually ```shell # to create a conda environment first: -# conda create -n idaes-examples python=3.10; conda activate idaes-examples +# conda create --yes --name idaes-examples python=3.10 && conda activate idaes-examples pip install -r requirements-dev.txt ``` From 2fa7d9171e182e08b4a9b02bc88ddaa4a8b37fab Mon Sep 17 00:00:00 2001 From: Ludovico Bianchi Date: Thu, 2 May 2024 21:36:27 -0500 Subject: [PATCH 5/5] Remove unused markdown import --- idaes_examples/browse.py | 3 --- 1 file changed, 3 deletions(-) diff --git a/idaes_examples/browse.py b/idaes_examples/browse.py index 9316fa9e..2a779efb 100644 --- a/idaes_examples/browse.py +++ b/idaes_examples/browse.py @@ -23,9 +23,6 @@ except: windll = None -# third-party -import markdown - # package import idaes_examples from idaes_examples.util import (