update usage guides, workflow guides, and notebooks#68
Conversation
…ebook This: - Update vessel search examples to use `vessel_search_result.vessel_ids` - Update vessel details workflow to use `vessels_result.vessel_ids` - Simplify start/end date logic using `.transmission_dates_from` and `.transmission_dates_to` - Pass list of vessel IDs(strings) to get vessel insights - Add documentation references to the Vessels API, Insights API and Vessel Viewer
This: - Document `result.vessel_ids` shortcut for passing matched vessel IDs to other APIs - Add documentation references to Vessels API, Insights API, and the Vessel Viewer
This: - Add examples and notes for filtering and obtaining Regions of Interest (ROIs) from (EEZ, MPA, RFMO) regions - Update guide and notebook outputs
This: - Update usage guides and notebook to demonstrate how to pass custom regions - Update type hint annotations and docstrings for the `geometry` parameter
This: - Update usage guides and notebook to demonstrate how to pass custom regions - Update examples to use the Reference Data API to fetch predefined regions of interest (ROIs) - Sync code block snippets and execution outputs across `4wings-api.md` and `4wings-api.ipynb` - Update type hint annotations and docstrings for the `geojson` parameter
…book This: - Update usage guides and notebook to demonstrate how to pass custom regions - Update examples to use the Reference Data API to fetch predefined regions of interest (ROIs) - Update type hint annotations and docstrings for the `geojson` parameter
This: - Update workflow to use the Reference Data API to fetch predefined regions of interest (ROIs) - Transition from fixed string date filters to dynamic windows using `datetime` - Re-run notebook cells to capture updated DataFrame outputs
lykmapipo
requested review from
aperdizs,
giselamo,
rrequero,
tomaslink and
yaaNuamahGFW
lykmapipo
added
documentation
yaaNuamahGFW
left a comment
yaaNuamahGFW
left a comment
There was a problem hiding this comment.
I left a few focused comments from the docs/API review. The main things are rendering correctness in the Events guide, one executable-doc typo, copied endpoint wording, and one cross-PR concern around showing full Reference API region objects before the request serialization is constrained to the documented region fields.
|
|
||
| **Output:** | ||
|
|
||
| ```` |
There was a problem hiding this comment.
I rendered this Markdown with pandoc and this malformed fence collapses the output plus the following Python example into one plain code block. The issue is the fence sequence here: four backticks open, two backticks close below, and the following Python block closes with four backticks. Could we normalize both snippets back to regular triple-backtick fences so the page renders correctly?
| }, | ||
| start_date="2017-01-01", | ||
| end_date="2017-01-31", | ||
| region=chn_eez_roi, |
There was a problem hiding this comment.
This example is good ergonomically, but it relies on the stacked region-support code serializing Reference API region objects down to the documented request shape. The GFW API docs show region bodies using dataset/id (and 4Wings buffer fields where relevant), while Reference API items also carry display metadata such as label, iso3, and sovereignty fields. If the serialization fix lands in the region-support PR, this docs example is fine; otherwise this guide should pass the minimal dict here, e.g. {"dataset": chn_eez_roi.dataset, "id": chn_eez_roi.id}, so users do not accidentally send extra region metadata.
| ] | ||
| ) | ||
| start_date = start_datetime.date() | ||
| start_date = start_date = min(vessels_result.transmission_dates_from) |
There was a problem hiding this comment.
Tiny executable-doc typo: this assigns start_date twice. It should just be start_date = min(vessels_result.transmission_dates_from).
|
|
||
| geojson (Optional[Union[GeoJson, str, Path, Dict[str, Any], SupportsGeoJsonInterface]], default=None): | ||
| Custom GeoJSON geometry to filter the bulk report. Either a path to a | ||
| Custom valid GeoJSON geometry to filter the events. Either a path to a |
There was a problem hiding this comment.
This looks copied from the Events docstring, but this parameter filters the bulk report, not events. Could we change this to 'Custom valid GeoJSON geometry to filter the bulk report' so the generated docs are endpoint-specific?
|
|
||
| geojson (Optional[Union[GeoJson, str, Path, Dict[str, Any], SupportsGeoJsonInterface]], default=None): | ||
| Custom GeoJSON geometry to filter the report. Either a path to a | ||
| Custom valid GeoJSON geometry to filter the events. Either a path to a |
There was a problem hiding this comment.
Same wording issue here: this is a 4Wings report endpoint, so 'filter the events' is misleading. Could we say 'filter the report' here and in the repeated 4Wings geojson parameter docstrings below?
aperdizs
left a comment
aperdizs
left a comment
There was a problem hiding this comment.
again, besides the Yaa comment, LGTM
3 participants
This:
geometry,geojsonetc.)geometryandgeojsonparameters