Adding docs for base unit classes and power plant #252
Conversation
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #252 +/- ##
==========================================
+ Coverage 78.44% 78.45% +0.01%
==========================================
Files 39 39
Lines 4259 4261 +2
==========================================
+ Hits 3341 3343 +2
Misses 918 918
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. |
There was a problem hiding this comment.
I don't think it is very helpful to duplicate about the same content as here:
https://assume.readthedocs.io/en/latest/assume.units.html#module-assume.units.powerplant
This is generated through automodule from the doc strings in the project.
If we add this twice, things will diverge and we will have old wrong docs over time.
Same for the BaseUnit - I think a small paragraph with a link to the reference above would be better?
I like the powerplant_params table loaded from csv - we should use that for the examples list maybe in the future?
But as far as I can see, the specific powerplant_params are already documented in the automodule above right?
Automodule of course has the benefit, that it always stays in line with the code
There was a problem hiding this comment.
Maybe we can update the doc strings instead to be more helpful
And use the units.rst to describe the general concept and point to the class descriptions of the powerplant, demand and co for the specific information?
There was a problem hiding this comment.
How would you suggest to have it? I would still prefer more text based description, because many people are scared of such code generated documentations and don't read them. Try to look at it as if you are not a computer scinetist, but a person just starting with coding and modeling.
But in general this is a valid point, maybe we @maurerle and @kim-mskw can meet next week to discuss the styling and make some guidelines for it?
There was a problem hiding this comment.
Of course.
I think we should take this as an example:
https://pypsa.readthedocs.io/en/latest/import_export.html
Which covers links to the API docs on a lot of places to dig deeper.
And shows how to actually use the framework.
Having a list of all Attributes to initialize objects as given here:
https://pypsa.readthedocs.io/en/latest/components.html
is also helpful, but it does not include methods of the classes (which is good).
|
format has changed, drop this |
-added base units class description
-added power plant description
-restructured contents