Improve documentation - Githubissues

pypsa-meets-earth / pypsa-distribution

GNU General Public License v3.0

10 stars 8 forks source link

Improve documentation #13

Open davide-f opened 1 year ago

davide-f commented 1 year ago

Describe the feature you'd like to see

Documentation shall be improved. In particular:

[x] 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 commented 1 year ago

@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 commented 12 months ago

I've tried to look on how to implement it

ekatef commented 12 months ago

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 commented 11 months ago

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

ekatef commented 11 months ago

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 commented 11 months ago

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

ekatef commented 9 months ago

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.