search

NREL / flasc

A rich floris-driven suite for SCADA analysis
https://nrel.github.io/flasc/
BSD 3-Clause "New" or "Revised" License
31 stars 18 forks source link

[BUG] Documentation is out of date and misleading #116

Open paulf81 opened 1 year ago

paulf81 commented 1 year ago

Is there an existing issue for this?

Current Behavior

FLASC documentation has fallen behind and has not been updated. Description of examples is inaccurate/incomplete, and some documentation (particularly pertaining to the energy_ratio module) need to be updated to reflect changes made in #80.

Expected Behavior

Updated documentation (and possibly README) to reflect current status of code.

misi9170 commented 9 months ago

I'm pushing this to v2.0. v2.0 will have significant restructuring of FLASC, and it makes sense to delay building out documentation until then.

ejsimley commented 7 months ago

I was going to add a documentation issue, but then saw this one, so I'll just add my support here!

I noticed a lot of functions are missing docstrings throughout the code (one example is the turbine_analysis.northing_offset module), and some need to be updated (for example, in ws_pw_curve_filtering.filter_by_power_curve, the arguments ws_deadband and pow_deadband aren't described in the doctstring).

Several of us should probably choose a few modules each and do a thorough review of the code and add missing documentation before the release.

paulf81 commented 7 months ago

I was going to add a documentation issue, but then saw this one, so I'll just add my support here!

I noticed a lot of functions are missing docstrings throughout the code (one example is the turbine_analysis.northing_offset module), and some need to be updated (for example, in ws_pw_curve_filtering.filter_by_power_curve, the arguments ws_deadband and pow_deadband aren't described in the doctstring).

Several of us should probably choose a few modules each and do a thorough review of the code and add missing documentation before the release.

100% agree, I think @misi9170 was also asking @rafmudaf how to generate API from docstrings so we should make sure to conform with that if we are going through the effort

Bartdoekemeijer commented 7 months ago

Good points -- and a lot of this is from my lack of discipline on documentation writing/maintenance! So please feel free to delegate some modules to me too.

paulf81 commented 7 months ago

No problem! I think it's all learning as we go and thank you!!!

misi9170 commented 5 months ago

Although this is partially addressed in #187, but I'm going to leave this open because I think there's still more to do here (the API documentation is not yet included, although we do have an open PR for this at #180)