Added the minimal example #257
Conversation
-added the first small jupyter example -added it to the documentation -improved docstrings for world class -improved docstrings for forecast class -adjusted the structure of documentation index -adjusted structure of automated docs -small fixes in several other docstings
assume/common/forecasts.py
Outdated
| Methods: | ||
| - __getitem__(self, column: str) -> pd.Series: Returns the forecast for a given column. | ||
| - get_availability(self, unit: str) -> pd.Series: Returns the availability of a given unit. | ||
| - get_price(self, fuel_type: str) -> pd.Series: Returns the price for a given fuel type or zeros if |
There was a problem hiding this comment.
This should not list available methods here too?
As this is provided directly from below - and we have docs per method, right?
There was a problem hiding this comment.
If they are removed here, will they still be visible in hints when coding? So you can see them directly?
There was a problem hiding this comment.
tbh I am not sure about common practices. Please advise
There was a problem hiding this comment.
ok, other packages don't do that. Is removed now. although somehow I would find it pretty cool if you could directly see available methods as a hint
There was a problem hiding this comment.
I just write:
object. then the IDE hints show which methods are available, which is mostly sufficient for me?
Other than that, I like clicking on the breadcrumbs in the menu to see an outline of my current open file:
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #257 +/- ##
=======================================
Coverage 78.44% 78.44%
=======================================
Files 39 39
Lines 4259 4259
=======================================
Hits 3341 3341
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.
We now have two different doc styles used in Assume.
Feel free to fix this now or in some time later.
I think that the added explanations are very useful and we can bulk convert the existing docs probably too.
I'll just approve without merge now.
I did not view the docs myself, but only looked at the github diff.
| data_format = "timescale" # "local_db" or "timescale" | ||
| example = "learning_small" | ||
| data_format = "local_db" # "local_db" or "timescale" | ||
| example = "small" |
There was a problem hiding this comment.
yes, since we don't expected people to already have docker running when using this small example.
| 5. Aggregates the fuel cost, emissions cost, and fixed cost to obtain the marginal cost of the | ||
| power plant. | ||
|
|
||
| Returns the resulting marginal cost as a float value. |
There was a problem hiding this comment.
If we want, we can change the docstring format from the default sphinx one:
https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html#an-example-class-with-docstrings
to Google Doc strings or Numpy doc strings:
https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html#example-google
or
https://www.sphinx-doc.org/en/master/usage/extensions/example_numpy.html#example-numpy
which adds the napoleon plugin.
But I think we should use the same code style all over assume.
There was a problem hiding this comment.
please explain, I don't understand
There was a problem hiding this comment.
Your doc style in this PR (Google Style) does not match the docstyle currently used (sphinx style) in all other files
sphinx style is this one:
:return: `True` if connection was successful, `False` otherwise
:rtype: bool
There was a problem hiding this comment.
Actually this isn't even google Style docs but something weird inbetween - Probably just a Copilot suggestion?
There was a problem hiding this comment.
ok, I get it now. So what I have written, it is basically google form with some extra explanation at the end. We can discuss this next time if we wanna keep it and convert existing stuff to it. I find it personally extremely helpful. Let's keep it for now and talk about it during a development meeting.
-added the first small jupyter example
-added it to the documentation
-improved docstrings for world class
-improved docstrings for forecast class
-adjusted the structure of documentation index
-adjusted structure of automated docs
-small fixes in several other docstings