Guidelines/conventions for algo/UDP descriptions #62
Description
This came up while reviewing a couple of description fixup PRs by @rahmandawibowo-vito :
- fix: update UDPs description and replace broken image links with raw github links #49
- fix: sync bap_composite udp description with the markdown docs #50
- fix: sync sentinel1_stats udp description with the markdown docs #54
- fix: sync max-ndvi composite udp description with the markdown docs #56
- fix: sync eurac_pv_farm_detection udp description with the markdown docs #57
It looks we're currently quite inconsistent with how algorithm and/or descriptions are handled:
- "eurac_pv_farm_detection":
- the algorithm has a description at algorithm_catalog/eurac_pv_farm_detection/eurac_pv_farm_detection_description.md\
- UDP has another descroption at openeo_udp/eurac_pv_farm_detection/README.md, which is copied (by generate.py) into openeo_udp/eurac_pv_farm_detection/eurac_pv_farm_detection.json
- fix: sync eurac_pv_farm_detection udp description with the markdown docs #57 tries to fix this by duplicating the decsription from algorithm_catalog/eurac_pv_farm_detection/eurac_pv_farm_detection_description.md to openeo_udp/eurac_pv_farm_detection/README.md . Note that that readme references an image pv_ml_output.png which is not duplicated, so the latter readme is kind of broken. The image could also be duplicated of course, but duplication like this is of course not ideal and will lead to long term maintainability problems.
- "sentinel1_stats": same kind of problem as "eurac_pv_farm_detection"
- "max_ndvi_composite" uses different solution: the UDP generate.py script explicitly links to the description markdown file from the algorithm description algorithm_catalog/max_ndvi_composite_files/max_ndvi_composite_description.md. Which eliminates the duplication problem, but instead causes a weird coupling issue: the UDP depends on a resource from the algorithm folder, while the algorithm itself actually doesn't directly use this resource.
tl;dr I think there is kind of confusion about whether what is described (algorithm vs UDP) and where it should be described (algorithm or UDP related folders).