Improvements of the documentation

[yerbol-akhmetov]

Changes proposed in this Pull Request

Good day. Here I propose changes to the documentation to improve its usefulness to new users.

Checklist

• [x] I consent to the release of this PR's code under the AGPLv3 license and non-code contributions under CC0-1.0 and CC-BY-4.0.
• [x] I tested my contribution locally and it seems to work fine.
• [ ] A note for the release notes doc/release_notes.rst is amended in the format of previous release notes, including reference to the requested PR.

[ekatef]

Hello @yerbol-akhmetov! Thank you so much to tackling this.

I can confirm that it absolutely makes sense to specify software and hardware requirements clearly.

As a suggestion, what if we would provide a super-short version of install commands close to the start of Installation section, like it's done for example in tensorflow docs? Could it work well for pypsa-earth, what do you think?

[yerbol-akhmetov]

Hello @yerbol-akhmetov! Thank you so much to tackling this.

I can confirm that it absolutely makes sense to specify software and hardware requirements clearly.

As a suggestion, what if we would provide a super-short version of install commands close to the start of Installation section, like it's done for example in tensorflow docs? Could it work well for pypsa-earth, what do you think?

Hi, @ekatef, thank you for suggestions! I am not sure how to add installation commands in short version. Most of them are app installation, which is generally performed based on the guidelines from website. Moreover, commands will be useful only for linux users I guess. However, if you can suggest clarify on that more, it would be helpful.

I have been thinking about something like to give an overview:

mamba env create -f envs/environment.yaml
conda activate pypsa-earth
snakemake -j 1 solve_all_networks

My feeling is that such an introduction may give better understanding on how the success in installation may look like. I recognise, however, that it may be quite misleading, especially for a first-time user.

Probably, we may add some testing rule to be as light as possible which could be using for the first run as our version of Hello world!. Sometimes, it may be very inspirational to see that at least something is working :) If you think it may help, happy to contribute such a testing script. Let me know please what do you think about that.

[yerbol-akhmetov]

Hello @yerbol-akhmetov! Thank you so much to tackling this. I can confirm that it absolutely makes sense to specify software and hardware requirements clearly. As a suggestion, what if we would provide a super-short version of install commands close to the start of Installation section, like it's done for example in tensorflow docs? Could it work well for pypsa-earth, what do you think?

Hi, @ekatef, thank you for suggestions! I am not sure how to add installation commands in short version. Most of them are app installation, which is generally performed based on the guidelines from website. Moreover, commands will be useful only for linux users I guess. However, if you can suggest clarify on that more, it would be helpful.

I have been thinking about something like to give an overview:

mamba env create -f envs/environment.yaml
conda activate pypsa-earth
snakemake -j 1 solve_all_networks

My feeling is that such an introduction may give better understanding on how the success in installation may look like. I recognise, however, that it may be quite misleading, especially for a first-time user.

Probably, we may add some testing rule to be as light as possible which could be using for the first run as our version of Hello world!. Sometimes, it may be very inspirational to see that at least something is working :) If you think it may help, happy to contribute such a testing script. Let me know please what do you think about that.

Hi, @ekatef. I think you are right. Activation of the environment and maybe some test might be good for the first user as "Hello world". Should it be added finally after all installation? Also it is important that it is not touching the tutorial part, I think, because then it might be misleading as previously.

[ekatef]

Probably, we may add some testing rule to be as light as possible which could be using for the first run as our version of Hello world!. Sometimes, it may be very inspirational to see that at least something is working :) If you think it may help, happy to contribute such a testing script. Let me know please what do you think about that.

Hi, @ekatef. I think you are right. Activation of the environment and maybe some test might be good for the first user as "Hello world". Should it be added finally after all installation? Also it is important that it is not touching the tutorial part, I think, because then it might be misleading as previously.

Super, thanks to the support! Actually, we are still long recommended to have such a test script. I'll try to propose a couple of suggestions to discuss today.

Great point about the tutorial part. I do agree and will keep it in mind.

[GbotemiB]

Hello @yerbol-akhmetov! Thank you so much to tackling this. I can confirm that it absolutely makes sense to specify software and hardware requirements clearly. As a suggestion, what if we would provide a super-short version of install commands close to the start of Installation section, like it's done for example in tensorflow docs? Could it work well for pypsa-earth, what do you think?

Hi, @ekatef, thank you for suggestions! I am not sure how to add installation commands in short version. Most of them are app installation, which is generally performed based on the guidelines from website. Moreover, commands will be useful only for linux users I guess. However, if you can suggest clarify on that more, it would be helpful. I have been thinking about something like to give an overview:

mamba env create -f envs/environment.yaml
conda activate pypsa-earth
snakemake -j 1 solve_all_networks

My feeling is that such an introduction may give better understanding on how the success in installation may look like. I recognise, however, that it may be quite misleading, especially for a first-time user. Probably, we may add some testing rule to be as light as possible which could be using for the first run as our version of Hello world!. Sometimes, it may be very inspirational to see that at least something is working :) If you think it may help, happy to contribute such a testing script. Let me know please what do you think about that.

Hi, @ekatef. I think you are right. Activation of the environment and maybe some test might be good for the first user as "Hello world". Should it be added finally after all installation? Also it is important that it is not touching the tutorial part, I think, because then it might be misleading as previously.

I think checking the version of snakemake can serve as "hello world" after activating the environment since snakemake is one of the important libraries that will be used in running the workflow. Most packages use this idea to confirm that a package has been successfully installed.

Also, I think we can include steps to generating the workflow dag into the documentation.

[ekatef]

Hey @yerbol-akhmetov! Thanks a lot for your great and much needed work. Have added a couple (rather minor) comments. Let me know please what is your feeling about that.

Generally, I'd suggest to work step-by-step merging a PR when you assume that it coverages some tasks, like improvement of the installation part or fixing the tutorial description. Usually, a merged PR gives a nice feeling of a thing being done ;) So, feel free to ping me please whenever you feel that some part of this work is about to be completed.

[davide-f]

Great effort @yerbol-akhmetov !! and great teamworking with reviews by @ekatef :D Merging :D