Improve documentation for installation and pytest instructions

[lbianchi-lbl]

Summary

• Update installation instructions in user-facing README so that they work properly after Replace idaesx gui command with simpler idaesx serve #104
• Improve clarity of pytest instructions in developer README to resolve Fixing instructions in developers README on how to run pytest #90 (i.e. we should be able to close Fixing instructions in developers README on how to run pytest #90 if the new text being proposed here is approved)

---

Legal Acknowledgement

By contributing to this software project, I agree to the following terms and conditions for my contribution:

I agree my contributions are submitted under the license terms described in the LICENSE.txt file at the top level of this directory.
I represent I am authorized to make the contributions and grant the license. If my employer has rights to intellectual property that includes these contributions, I represent that I have received permission to make contributions and grant the required license on behalf of that employer.

---

📚 Documentation preview 📚: https://idaes-examples--106.org.readthedocs.build/en/106/

[andrewlee94]

I didn't spend much time, but it looks good to me.

[bpaul4]

Looks good to me, as well.

[JavalVyas2000]

I am able to run the single file test only form idaes_example directory with the command mentioned in the documentation with -v flag. Whereas if I use -c flag, I can test the notebook from any level. I am not sure why that is the case. I would suggest either adding the directory level in the documentation from where the tests should be ran with the current command or change the flag to -c.

The error I get with -v flag in other directory levels are:

INTERNALERROR> Traceback (most recent call last):
INTERNALERROR>   File "C:\Users\javal\anaconda3\envs\idaes-pse\lib\site-packages\_pytest\main.py", line 281, in wrap_session
INTERNALERROR>     config._do_configure()     
INTERNALERROR>   File "C:\Users\javal\anaconda3\envs\idaes-pse\lib\site-packages\_pytest\config\__init__.py", line 1121, in _do_configure 
INTERNALERROR>     self.hook.pytest_configure.call_historic(kwargs=dict(config=self))       
INTERNALERROR>   File "C:\Users\javal\anaconda3\envs\idaes-pse\lib\site-packages\pluggy\_hooks.py", line 523, in call_historic
INTERNALERROR>     res = self._hookexec(self.name, self._hookimpls.copy(), kwargs, False)   
INTERNALERROR>   File "C:\Users\javal\anaconda3\envs\idaes-pse\lib\site-packages\pluggy\_manager.py", line 119, in _hookexec
INTERNALERROR>     return self._inner_hookexec(hook_name, methods, kwargs, firstresult)     
INTERNALERROR>   File "C:\Users\javal\anaconda3\envs\idaes-pse\lib\site-packages\pluggy\_callers.py", line 138, in _multicall
INTERNALERROR>     raise exception.with_traceback(exception.__traceback__)
INTERNALERROR>   File "C:\Users\javal\anaconda3\envs\idaes-pse\lib\site-packages\pluggy\_callers.py", line 102, in _multicall
INTERNALERROR>     res = hook_impl.function(*args)
INTERNALERROR>   File "C:\Users\javal\Desktop\Internship\IDAES-examples\idaes_examples\notebooks\conftest.py", line 167, in pytest_configure
INTERNALERROR>     NotebookPrep.configure(config)
INTERNALERROR>   File "C:\Users\javal\Desktop\Internship\IDAES-examples\idaes_examples\notebooks\conftest.py", line 111, in configure     
INTERNALERROR>     raise RuntimeError(        
INTERNALERROR> RuntimeError: Preprocessing not completed in 10 seconds. Check logs of 'master' process: tests_gw0.log

[lbianchi-lbl]

• @lbianchi-lbl: test new version of docs on Windows
• @JavalVyas2000: repeat tests for a few different combinations making sure to note all relevant information:
  • Exact command
  • Output (text or screenshot)
  • Directory from where the command was issued (i.e. working directory)

[JavalVyas2000]

For testing single notebook, I performed the following tests and got the following results.

The following command is ran from different levels in the repository.

pytest -v idaes_examples/notebooks/docs/unit_models/operations/compressor_test.ipynb

1. Root directory:

ERROR: usage: pytest [options] [file_or_dir] [file_or_dir] [...]
pytest: error: unrecognized arguments: --nbmake --nbmake-timeout=600 -n idaes_examples/notebooks/docs/unit_models/operations/compressor_test.ipynb
  inifile: C:\Users\javal.vyas\Desktop\github\IDAES-examples\idaes_examples\pytest.ini
  rootdir: C:\Users\javal.vyas\Desktop\github\IDAES-examples\idaes_examples

2. idaes_example:

ERROR: usage: pytest [options] [file_or_dir] [file_or_dir] [...]
pytest: error: unrecognized arguments: --nbmake --nbmake-timeout=600 -n idaes_examples/notebooks/docs/unit_models/operations/compressor_test.ipynb
  inifile: C:\Users\javal.vyas\Desktop\github\IDAES-examples\idaes_examples\pytest.ini
  rootdir: C:\Users\javal.vyas\Desktop\github\IDAES-examples\idaes_examples

If I change the flag to -c instead of -v, then the outputs are as follows:

Command used: pytest -c idaes_examples/notebooks/docs/unit_models/operations/compressor_test.ipynb 

1. Root directetory:

_______________ ERROR collecting idaes_examples/tests/test_browse.py ________________ 
ImportError while importing test module 'C:\Users\javal.vyas\Desktop\github\IDAES-examples\idaes_examples\tests\test_browse.py'.
Hint: make sure your test modules/packages have valid Python names.
Traceback:
..\..\..\AppData\Local\anaconda3\envs\idaes-pse\lib\importlib\__init__.py:126: in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
idaes_examples\tests\test_browse.py:3: in <module>
    from idaes_examples import browse
idaes_examples\browse.py:27: in <module>
    import markdown
E   ModuleNotFoundError: No module named 'markdown'

After installing markdown, this works and passes the tests

idaes_examples\notebooks\docs\unit_models\operations\idaes_examples\tests\test_base.py
 . [  9%]
                                                                               [  9%]
idaes_examples\notebooks\docs\unit_models\operations\idaes_examples\tests\test_browse.py . [ 18%]
                                                                               [ 18%] 
idaes_examples\notebooks\docs\unit_models\operations\idaes_examples\tests\test_build.py . [ 27%]
...                                                                            [ 54%]
idaes_examples\notebooks\docs\unit_models\operations\idaes_examples\tests\test_informational.py . [ 63%]
                                                                               [ 63%] 
idaes_examples\notebooks\docs\unit_models\operations\idaes_examples\tests\test_notebooks.py . [ 72%]
...                                                                            [100%]

2. Running from idaes_example directory:

..\..\..\..\AppData\Local\anaconda3\envs\idaes-pse\lib\site-packages\pluggy\_manager.py:168: in register
    hook._maybe_apply_history(hookimpl)
..\..\..\..\AppData\Local\anaconda3\envs\idaes-pse\lib\site-packages\pluggy\_hooks.py:569: in _maybe_apply_history
    res = self._hookexec(self.name, [method], kwargs, False)
..\..\..\..\AppData\Local\anaconda3\envs\idaes-pse\lib\site-packages\pluggy\_manager.py:119: in _hookexec
    return self._inner_hookexec(hook_name, methods, kwargs, firstresult)
notebooks\conftest.py:167: in pytest_configure
    NotebookPrep.configure(config)
notebooks\conftest.py:111: in configure
    raise RuntimeError(
E   RuntimeError: Preprocessing not completed in 10 seconds. Check logs of 'master' process: tests_gw0.log

[lbianchi-lbl]

I'm still working on running the full set of tests, but I can already report that something strange is going on.

Starting from a clean Conda env and local clone, after running pip install -r requirements-dev.txt, running pytest . from the repo root results in an error:

Neither increasing the timeout in FIXME and/or running idaesx pre before re-running pytest . seems to help:

Running pytest idaes_examples, killing the process(es) with Ctrl+C, and then re-running pytest . seems to work:

On Linux, pytest . works as expected on the first try:

This is with a fresh environment, but not in a fresh directory. After creating a fresh clone in a temp directory:

Using the same "trick" of starting and cancelling a run of pytest idaes_examples, the first attempt is not successful:

Only after waiting a bit longer before hitting Ctrl-C, so that the first test is run, does the "trick" work:

---

Back on Windows, pytest -v idaes_examples\notebooks\docs\unit_models\operations\compressor_test.ipynb seems to work:

The same with Unix-style / separators also works:

---

After creating another fresh clone + Conda env, this is the result of running pytest -v idaes_examples/notebooks/docs/unit_models/operations/compressor_test.ipynb:

The same on Linux results in the same error:

[lbianchi-lbl]

OK, I think I have a better idea of what might be happening. I think these might actually due to a few different causes. Also, note that these are just hypotheses on my side, and therefore might be inaccurate or completely wrong.

For testing single notebook, I performed the following tests and got the following results.

The following command is ran from different levels in the repository.

pytest -v idaes_examples/notebooks/docs/unit_models/operations/compressor_test.ipynb

1. `Root directory:`

ERROR: usage: pytest [options] [file_or_dir] [file_or_dir] [...]
pytest: error: unrecognized arguments: --nbmake --nbmake-timeout=600 -n idaes_examples/notebooks/docs/unit_models/operations/compressor_test.ipynb
  inifile: C:\Users\javal.vyas\Desktop\github\IDAES-examples\idaes_examples\pytest.ini
  rootdir: C:\Users\javal.vyas\Desktop\github\IDAES-examples\idaes_examples

I believe that this error and the following are caused by the environment where these commands were run; more specifically, the package nbmake, which is required to run the notebook tests, and which defines the pytest command line options that cause the error above, was not installed.

nbmake should be installed automatically when running pip install -r requirements-dev.txt, so either that command wasn't run after creating the idaes-examples Conda env, or the idaes-examples Conda env wasn't active.

2. `idaes_example:`

ERROR: usage: pytest [options] [file_or_dir] [file_or_dir] [...]
pytest: error: unrecognized arguments: --nbmake --nbmake-timeout=600 -n idaes_examples/notebooks/docs/unit_models/operations/compressor_test.ipynb
  inifile: C:\Users\javal.vyas\Desktop\github\IDAES-examples\idaes_examples\pytest.ini
  rootdir: C:\Users\javal.vyas\Desktop\github\IDAES-examples\idaes_examples

Same as above. Plus, there's another issue with the path: if the working directory is idaes_examples, then running pytest idaes_examples/notebooks/docs/unit_models/operations/compressor_test.ipynb doesn't make much sense since that's supposed to be a relative path to an existing file. Thus, the command need to be adapted when running from directories other than the repo root, e.g. from idaes_examples, the command should be pytest notebooks/docs/unit_models/operations/compressor_test.ipynb.

For the sake of simplicity and consistency, at this point my recommendation would just be to always run commands from the root of the repository (and I'll add a change to README-developer.md to that effect).

If I change the flag to -c instead of -v, then the outputs are as follows:

Command used: pytest -c idaes_examples/notebooks/docs/unit_models/operations/compressor_test.ipynb 

1. `Root directetory:`

_______________ ERROR collecting idaes_examples/tests/test_browse.py ________________ 
ImportError while importing test module 'C:\Users\javal.vyas\Desktop\github\IDAES-examples\idaes_examples\tests\test_browse.py'.
Hint: make sure your test modules/packages have valid Python names.
Traceback:
..\..\..\AppData\Local\anaconda3\envs\idaes-pse\lib\importlib\__init__.py:126: in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
idaes_examples\tests\test_browse.py:3: in <module>
    from idaes_examples import browse
idaes_examples\browse.py:27: in <module>
    import markdown
E   ModuleNotFoundError: No module named 'markdown'

The markdown package should be installed automatically after running pip install -r requirements-dev.txt:

So, the fact that markdown was not found is another hint that the environment where these commands were run was not the one where pip install -r requirements-dev.txt from an IDAES/examples clone had been previously run.

After installing markdown, this works and passes the tests

idaes_examples\notebooks\docs\unit_models\operations\idaes_examples\tests\test_base.py
 . [  9%]
                                                                               [  9%]
idaes_examples\notebooks\docs\unit_models\operations\idaes_examples\tests\test_browse.py . [ 18%]
                                                                               [ 18%] 
idaes_examples\notebooks\docs\unit_models\operations\idaes_examples\tests\test_build.py . [ 27%]
...                                                                            [ 54%]
idaes_examples\notebooks\docs\unit_models\operations\idaes_examples\tests\test_informational.py . [ 63%]
                                                                               [ 63%] 
idaes_examples\notebooks\docs\unit_models\operations\idaes_examples\tests\test_notebooks.py . [ 72%]
...                                                                            [100%]

Here something strange is happening: the test seem to be running (although it's hard to say without the complete pytest output), but note that the paths that pytest is reporting do not actually exist. It looks like pytest is somehow concatenating the parent directory of the file being passed as an argument (i.e.. idaes_examples\notebooks\docs\unit_models\operations\) with the path to the actual tests relative to the current working directory (i.e. idaes_examples\tests\test_notebooks.py, etc). My guess why this happens is that the -c flag is used to specify a configuration file. Since the provided path (i.e. idaes_examples\notebooks\docs\unit_models\operations\compressor_test.ipynb) is not of any format that pytest recognizes as a config file, it ignores it, and instead takes its parent directory as the rootdir or basedir (again, here it would be useful to have the complete pytest output).

I tried running this command, but couldn't reproduce the result above: in my case, it just crashes because of the RuntimeError timeout described in my previous comment (which is also what happens with your next attempt).

2. Running from idaes_example directory:

..\..\..\..\AppData\Local\anaconda3\envs\idaes-pse\lib\site-packages\pluggy\_manager.py:168: in register
    hook._maybe_apply_history(hookimpl)
..\..\..\..\AppData\Local\anaconda3\envs\idaes-pse\lib\site-packages\pluggy\_hooks.py:569: in _maybe_apply_history
    res = self._hookexec(self.name, [method], kwargs, False)
..\..\..\..\AppData\Local\anaconda3\envs\idaes-pse\lib\site-packages\pluggy\_manager.py:119: in _hookexec
    return self._inner_hookexec(hook_name, methods, kwargs, firstresult)
notebooks\conftest.py:167: in pytest_configure
    NotebookPrep.configure(config)
notebooks\conftest.py:111: in configure
    raise RuntimeError(
E   RuntimeError: Preprocessing not completed in 10 seconds. Check logs of 'master' process: tests_gw0.log

This matches my attempt mentioned above. I still don't know exactly what's causing this error (and why running the notebook tests seems to "fix" it), but my guess is that it's connected to the preprocessing step implemented in conftest.py, and whether the parallel execution options are active or not, which again is related with which config file is considered (pyproject.toml vs idaes_examples/pytest.ini).

In any case, the name of the environment in the stack trace (idaes-pse) makes me thing that these commands where run in an environment that doesn't have the full set of IDAES/examples dev dependencies.

---

In summary: all of this is very complicated, most of which due to how the tests are set up and the documentation being ambiguous or misleading in certain passages, and I apologize for the confusion. I think the main takeaways from my point of view would be:

• Ensure that the correct Conda env (idaes-examples) is activated and that all developer dependencies are installed in it by running pip install -r requirements-dev.txt after activating it
• Run all pytest commands from the root of the repository; use the pytest command-line argument and options (as opposed to navigating to other working directories) to specify which tests to run, according to the updated developer instructions
• Because of a potential bug that's still not completely understood, running pytest . immediately after cloning (i.e. running that as the very first command in a fresh clone) will fail, and will start working again only after running pytestn idaes_examples once
  • UPDATE: this is now being tracked in Running pytest . after cloning fails with RuntimeError: Preprocessing not completed in 10 seconds #112
• The experiments described in my comments above seem to suggest that this is unrelated to using the -c flag, although I haven't been able to reproduce the behavior reported by @JavalVyas2000

[andrewlee94]

@lbianchi-lbl Is this ready to merge?