Improve documentation

[davide-f]

Describe the feature you'd like to see

Documentation shall be improved. In particular:

• Add readthedocs
• Improve docstrings
• Add more description of the distribution repo.
  E.g. (thanks katia):
  • what are the main inputs needed to run the model and under which assumptions are obtained approximations of these inputs?
  • which configuration parameters should be looked for to adjust the model configuration?
  • a short description related to the essence of the problems which can be solved by the model (I think, a picture and a couple of reference to the published works would work great)

[ekatef]

@davide-f Thanks a lot for adding the issue on docs.

Adding a couple of suggestions after some playing with the code. According to my impression, it would be great to have answers on the following questions:
[ ] what are the main inputs needed to run the model and under which assumptions are obtained approximations of these inputs?
[ ] which configuration parameters should be looked for to adjust the model configuration?
[ ] a short description related to the essence of the problems which can be solved by the model (I think, a picture and a couple of reference to the published works would work great)

@davide-f does it sound reasonable for you? Obviously, happy to contribute to each of the points.

[TomFer97]

I've tried to look on how to implement it

[ekatef]

I've tried to look on how to implement it

Hey @TomFer97! That is amazing :)

Which tools do you consider?

Could be pypsa-earth experience probably helpful? It is based on using sphinx, which allows to use markdown syntax, using read-the-docs infrastructure to host the docs and use some nice automated features like fetching doc-strings and rendering config tables. (Sorry if it sounds trivial for you!)

[TomFer97]

It's the first experience for me in this kind of thing. I'll to come up with something for friday :)

[ekatef]

It's the first experience for me in this kind of thing. I'll to come up with something for friday :)

Then, sphinx may be a way to go :)
There are some practical hints on how to start.

[davide-f]

FYI, a draft implementation of readthedocs is online :)
https://pypsa-distribution.readthedocs.io/en/latest/

[ekatef]

It may be worth to add a brief explanation on how to run a tutorial case and a full-scale simulation. In particular, would be great to mention a proper set-up of tutorial parameter in config.pypsa-earth.yaml to avoid issues described in #22.