Add a FAQ section to the documentation

[ekatef]

There is a number of practical questions which do not really fit into the proper documentation structure but arise receptively. It looks like this kind of information can be kept as "Frequently Asked Questions". Currently this list may look like this:

• how to clean-up the powerplantmatching data folder (to avoid the "energy-source problem")
  The solution is described here.
• how to update the environment: conda env update -f envs/environment.yaml (works on an activated environment, see https://stackoverflow.com/a/43873901/8465924)

Note: sometimes it's necessary to uninstall and reinstall package in the environment to get it work. That is in particular the case when a package source has changed recently

• good patterns of git workflow:
  • how to keep your repository updated (there is currently an excellent explanation by @Emre-Yorat89 in the discussion)
  • a PR workflow

   git checkout -b "pr_branch"
  make changes in the notebook & compile once
  git status # to check what changed ->>> This will give you the list of names e.g. notebooks/base_network.ipynb
  git add <name of the notebook>
  git commit -m "message"
  git push
  git checkout main
  

• reset the fork (@davide-f many thanks for instructions!)

It can be very useful if your fork needs some clean-up. Please use the instructions bellow with caution as they drop changes in your main branch setting its' state according to the upstream/main.

git remote add upstream https://github.com/pypsa-meets-earth/pypsa-earth
git fetch upstream
git checkout main
git pull upstream main
# this will delete all your local changes to master
git reset --hard upstream/main
# take care, this will delete all your changes on your forked master
git push origin main --force

Adapted from reference

• how to rerun Snakemake workflow
  sometimes it may be tricky to re-run the workflow on the prepared data, in particular due to input files updated by another job (even it's not the case). Using --rerun-triggers with mtime argument does resolve this problem.

  This issue is connected with some changes in the re-run behaviour of Snakemake. See this SO discussion for the details.

    snakemake -j 1 solve_all_networks --rerun-triggers mtime

[ekatef]

It seems that it could make sense to add a troubleshooting guide for installation PyPSA-Earth on Windows. The known problems are:

1. Issues with installation of a virtual environment. This Youtube tutorial can help.
2. Administrator privileges are needed. An example of a typical error ~/pypsa-earth\lib\site-packages\snakemake\jobs.py", line 909, in prepare os.symlink(os.path.abspath(source), link) OSError: [WinError 1314] A required privilege is not held by the client

Generally, Windows Subsystem for Linux can be recommended as an effective universal solution

[ekatef]

As a quick fix, adding here an instruction on how to use pre-commit (@davide-f, thanks a lot for writing it!):

If you are using vscode, you may use the pre-commit locally with:

in view-command pallette-> Python: Select intepreter-> PyPSA-Earth
open a new terminal view->command pallette->new terminal
in the terminal digit "conda activate pypsa-earth" (if not already in the env)
digit "pre-commit install"
After this, the pre-commit should be installed for the local repository.
This should be repeated for every local repositories you may be using this.

[ekatef]

A short trouble-shooting guide would be helpful to support set-up of the model. The simplest steps which are often helpful:

1. remove all the output of the workflow (the whole network folder and content of resouces folder, except natura.tiff);
2. update the local pypsa-earth repository with git pull;
3. update pypsa-earth environment with mamba env update --file envs/environment.yaml --prune