Add updated installation instructions by dalonsoa · Pull Request #138 · EnergySystemsModellingLab/MUSE_OS

dalonsoa · 2023-07-20T06:07:59Z

Description

Adds thorough and up-to-date installation instructions to the documentation available in Read the Docs. It also removes most of the information in the README (that needs updating one the documentation is live) so there is only one set of instructions, to avoid conflict.

Focus the review in installation.rst. Modifying the other files are just side effects. You can find the rendered version of these instructions in https://muse-os.readthedocs.io/en/new_installation/installation.html

Fixes #133
Fixes #109
Fixes #132

Type of change

Please add a line in the relevant section of
CHANGELOG.md to
document the change (include PR #) - note reverse order of PR #s.

New feature (non-breaking change which adds functionality)
Optimization (non-breaking, back-end change that speeds up the code)
Bug fix (non-breaking change which fixes an issue)
Breaking change (whatever its nature)

Key checklist

All tests pass: $ python -m pytest
The documentation builds and looks OK: $ python -m sphinx -b html docs docs/build

Further checks

N/A

Code is commented, particularly in hard-to-understand areas
Tests added that prove fix is effective or that feature works

sgiarols

Here my comments.
I worked n a Windows machine and could test the procedure with pyenv and pipx on Windows.
venv did not work.

In general, I wonder whether venv is really useful as a developer may be familiar already with Anaconda and prefer to use Anaconda platform

docs/installation.rst

sgiarols · 2023-07-20T06:21:12Z

docs/installation.rst

+
+The main page for the documentation can then be found at ``docs/build/html/index.html`` and the file can viewed from any web browser.
+
+Configuring VSCode


Can we mention editors alternative to VSCode can be used?

Sure. If you are using a different editor, maybe you can write some instructions. The more instructions, the better!

sgiarols · 2023-07-20T06:30:41Z

README.md


-### Recommended way
+MUSE is available in `PyPI` and therefore it can be installed easily with `pip`. Detailed instructions on how to do that ensuring the right version of Python is used can be found in the Documentation.



It is fine to have the instructions only on one side to avoid repetitions. We would need a direct link to the documentation from the README file.

In the text of the PR it is indicated that the README needs updating once this is merge. I cannot update the README until that happens.

Oh, OK, so I misunderstood and the README would still have back again the info on the installation once the doc is updated.

No, I think I was not clear either. The README will be short, as I have left it, but the link to the documentation in RdDs cannot be added until this is merged because there's nothing to point to (I can point to the documentation overall, but not to the specific sections of it because those have changed). Is it clearer?

docs/installation.rst

sgiarols · 2023-07-20T08:39:12Z

docs/installation.rst

+
+Creating a virtual environment with ``venv``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+


I am a bit unsure that having venv would be useful. Compared to conda approach, it does not allow to know the decide the python version, compared to pyenv we still need to build an environment

As a professional developer, I refuse to use conda and prefer, by a long shot, venv, so I will keep it for sure. It is way faster, despite not letting you choose the python version. conda tries to do everything and the result is pretty poor.

docs/installation.rst

sgiarols · 2023-07-20T08:48:10Z

docs/installation.rst

+In the developing phase, MUSE can also be used to run test cases to check that the model would reproduce expected results from a defined set of input data. Tests can be run with the command [pytest](https://docs.pytest.org/en/latest/), from the testing framework of the same name.
+
+Within the ``MUSE-OS`` directory, just run:
+


We should say what needs to be checked to understand whether a user is in the MUSE-OS directory. Maybe we could have a screenshot showing the path on the command line.

Maybe, but please let's keep in mind that we are talking about people aiming to develop MUSE. By necessity, they need to have some level of competency and know what they are doing.

sgiarols · 2023-07-20T08:53:21Z

docs/installation.rst

+----------------------------
+
+Developers of MUSE will need to have the version control tool ``git`` installed in their system and be familiar with its usage. The `Introduction to Git and GitHub for software development <https://imperialcollegelondon.github.io/introductory_grad_school_git_course/>`_ course created by `Imperial RSE Team <https://www.imperial.ac.uk/admin-services/ict/self-service/research-support/rcs/service-offering/research-software-engineering/>`_ can be a good place to start.
+


We may need the few instructions here to install git

To be honest, if anyone wants to develop MUSE, they will need to have a bit of initiative and follow up on the resources provided. There's no point of giving everything this low level having so many excellent resources and guides out there, specially to someone who intends to become a developer. A certain level of competency on that front is to be required. But that's just my opinion.

dalonsoa · 2023-07-20T09:06:47Z

README.md


-### Recommended way
+MUSE is available in `PyPI` and therefore it can be installed easily with `pip`. Detailed instructions on how to do that ensuring the right version of Python is used can be found in the Documentation.



In the text of the PR it is indicated that the README needs updating once this is merge. I cannot update the README until that happens.

docs/installation.rst

dalonsoa · 2023-07-20T09:25:13Z

docs/installation.rst

+----------------------------
+
+Developers of MUSE will need to have the version control tool ``git`` installed in their system and be familiar with its usage. The `Introduction to Git and GitHub for software development <https://imperialcollegelondon.github.io/introductory_grad_school_git_course/>`_ course created by `Imperial RSE Team <https://www.imperial.ac.uk/admin-services/ict/self-service/research-support/rcs/service-offering/research-software-engineering/>`_ can be a good place to start.
+


To be honest, if anyone wants to develop MUSE, they will need to have a bit of initiative and follow up on the resources provided. There's no point of giving everything this low level having so many excellent resources and guides out there, specially to someone who intends to become a developer. A certain level of competency on that front is to be required. But that's just my opinion.

docs/installation.rst

dalonsoa · 2023-07-20T09:29:15Z

docs/installation.rst

+In the developing phase, MUSE can also be used to run test cases to check that the model would reproduce expected results from a defined set of input data. Tests can be run with the command [pytest](https://docs.pytest.org/en/latest/), from the testing framework of the same name.
+
+Within the ``MUSE-OS`` directory, just run:
+


Maybe, but please let's keep in mind that we are talking about people aiming to develop MUSE. By necessity, they need to have some level of competency and know what they are doing.

dalonsoa · 2023-07-20T09:30:18Z

docs/installation.rst

+
+The main page for the documentation can then be found at ``docs/build/html/index.html`` and the file can viewed from any web browser.
+
+Configuring VSCode


Sure. If you are using a different editor, maybe you can write some instructions. The more instructions, the better!

dalonsoa · 2023-07-20T13:02:27Z

I think I've address or answered all of your comments, @sgiarols , but please let me know if there's anything that does not look right.

sgiarols · 2023-07-20T14:49:25Z

I think I've address or answered all of your comments, @sgiarols , but please let me know if there's anything that does not look right.

Thanks. I think it all looks good. I only have two questions left.

do you think it is worth adding virtualenv
do we need the alias instructions

dalonsoa · 2023-07-21T04:18:28Z

For what I can tell, venv and virtualenv` are really similar, so I'm not sure it is worth adding it to the mix. See comments in Stackoverflow.

About the alias, many people will not need it - obviously not those that do not use Windows. But if you have that problem that whenever you try to run Python, you get the Microsoft Store, it will be difficult to figure out what is going on and how to fix it without some direction. I would leave it, just in case.

I've follow these instructions in a MacOS and two pristine Windows computer. In one, I had the problem with the alias, but in the other I didn't, so...

ahawkes · 2023-07-21T08:42:21Z

Indeed, it is confusing an unnerving for a new user to see a warning in a very basic example, and the explanation that wind is somehow outside the system boundaries is also confusing and reduces confidence in the model. What exactly is going on here? A

# Conflicts: # docs/installing-muse.rst

…into new_installation

sgiarols · 2023-07-21T14:59:35Z

Indeed, it is confusing an unnerving for a new user to see a warning in a very basic example, and the explanation that wind is somehow outside the system boundaries is also confusing and reduces confidence in the model. What exactly is going on here? A

MUSE is saying that no process is producing wind in the current case study. We can simply address this problem in the case definition.

sgiarols · 2023-08-02T08:14:30Z

docs/installation.rst

+    -- 2023-07-20 13:45:25 - muse.mca - INFO
+    Finish simulation year 2050!
+



-- 2023-08-02 09:11:50 - muse.sectors.sector - INFO
Running gas for year 2050

-- 2023-08-02 09:11:50 - muse.interactions - INFO
Net new_to_retro of 1 interactions interacting via transfer

-- 2023-08-02 09:11:50 - muse.hooks - INFO
Computing initial_asset_transform: default

-- 2023-08-02 09:11:50 - muse.hooks - INFO
Computing initial_asset_transform: clean

-- 2023-08-02 09:11:50 - muse.demand_share - INFO
Computing demand_share: default

-- 2023-08-02 09:11:51 - muse.production - INFO
Computing production: max

-- 2023-08-02 09:11:51 - muse.production - INFO
Computing production: max

-- 2023-08-02 09:11:51 - muse.production - INFO
Computing production: share

-- 2023-08-02 09:11:51 - muse.mca - INFO
Finish simulation year 2050!

@dalonsoa , I updated screenshot of model results. This can substitute your lines.

sgiarols

Remembering we needed to update the model output before merging this PR

Add uptodate installation instructions

8e6c6d7

dalonsoa requested review from ahawkes, martinstringer and sgiarols July 20, 2023 06:08

dalonsoa added 2 commits July 20, 2023 07:10

Remove unused dependency

dd72863

Fix wrong formating of links

65aab2e

sgiarols reviewed Jul 20, 2023

View reviewed changes

dalonsoa commented Jul 20, 2023

View reviewed changes

dalonsoa added 4 commits July 20, 2023 13:39

Clarify summary note

bbad461

Add output simulation

1dba66a

Clarify the use of venv

8cdb957

Be agnostic on the environment to use when installing MUSE from source

b7b8c73

Merge branch 'develop' into new_installation

69b9328

dalonsoa added 3 commits July 21, 2023 11:31

Merge branch 'develop' into new_installation

c24f555

# Conflicts: # docs/installing-muse.rst

Merge branch 'new_installation' of https://github.com/SGIModel/MUSE_OS …

840a085

…into new_installation

Update changelog

e1f719d

dalonsoa added 4 commits July 28, 2023 08:15

Generalize the number of python alias to disable in Windows

cf73c23

Fix typo and make some rewording to clarify instructions

9db6aee

Add note on using py in Windows

326c273

Merge branch 'develop' into new_installation

dc8c931

sgiarols approved these changes Aug 2, 2023

View reviewed changes

sgiarols reviewed Aug 2, 2023

View reviewed changes

Update output example of running simulation

8f4dec6

dalonsoa merged commit b32e6a7 into develop Aug 2, 2023

dalonsoa deleted the new_installation branch August 2, 2023 09:29


		The main page for the documentation can then be found at ``docs/build/html/index.html`` and the file can viewed from any web browser.

		Configuring VSCode


		### Recommended way
		MUSE is available in `PyPI` and therefore it can be installed easily with `pip`. Detailed instructions on how to do that ensuring the right version of Python is used can be found in the Documentation.


		Creating a virtual environment with ``venv``
		^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

		In the developing phase, MUSE can also be used to run test cases to check that the model would reproduce expected results from a defined set of input data. Tests can be run with the command [pytest](https://docs.pytest.org/en/latest/), from the testing framework of the same name.

		Within the ``MUSE-OS`` directory, just run:

		----------------------------

		Developers of MUSE will need to have the version control tool ``git`` installed in their system and be familiar with its usage. The `Introduction to Git and GitHub for software development <https://imperialcollegelondon.github.io/introductory_grad_school_git_course/>`_ course created by `Imperial RSE Team <https://www.imperial.ac.uk/admin-services/ict/self-service/research-support/rcs/service-offering/research-software-engineering/>`_ can be a good place to start.

		-- 2023-07-20 13:45:25 - muse.mca - INFO
		Finish simulation year 2050!

Comments

Conversation

dalonsoa commented Jul 20, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Type of change

Key checklist

Further checks

Uh oh!

sgiarols left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dalonsoa commented Jul 20, 2023

Uh oh!

sgiarols commented Jul 20, 2023

Uh oh!

dalonsoa commented Jul 21, 2023

Uh oh!

ahawkes commented Jul 21, 2023 via email • edited by dalonsoa Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sgiarols commented Jul 21, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sgiarols Aug 2, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sgiarols left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

dalonsoa commented Jul 20, 2023 •

edited

Loading

ahawkes commented Jul 21, 2023 via email •

edited by dalonsoa

Loading

sgiarols commented Jul 21, 2023 •

edited

Loading

sgiarols Aug 2, 2023 •

edited

Loading