docs: add api workflow guides and jupyter notebooks

This also:
- enable MyST-NB for rendering and executing Markdown and Jupyter notebooks
- configure notebook execution settings for docs builds
- add workflow guides to documentation navigation and index
- link workflow guides from getting started and usage guides

Author: lykmapipo

docs/source/conf.py

@@ -34,8 +34,8 @@
     "sphinx.ext.autodoc",
     "sphinx.ext.intersphinx",
     # third-party extensions
-    "myst_parser",
-    # "myst_nb",
+    # "myst_parser", # imported by myst_nb automatically
+    "myst_nb",
     "autodoc2",
     "sphinx_copybutton",
     "sphinx_inline_tabs",
@@ -47,7 +47,8 @@
 # The suffix of source filenames.
 source_suffix = {
     ".rst": "restructuredtext",
-    ".md": "markdown",
+    ".md": "myst-nb",
+    ".ipynb": "myst-nb",
 }
 
 # The master toctree document.
@@ -95,6 +96,16 @@
 ]
 myst_heading_anchors = 3
 
+# -- MyST-NB execution configuration ------------------------------------------
+# https://myst-nb.readthedocs.io/en/latest/configuration.html#config-intro
+
+nb_execution_mode = "force"
+nb_execution_timeout = 300
+nb_execution_raise_on_error = True
+
+nb_output_stderr = "show"
+nb_merge_streams = True
+
 
 # -- Options for autodoc2 -------------------------------------------------
 # https://sphinx-autodoc2.readthedocs.io/en/latest/config.html

docs/source/getting-started.md

@@ -226,6 +226,6 @@ memory usage: 43.7+ KB
 
 This guide has provided you with the fundamental steps to install and use the `gfw-api-python-client` for making basic API requests.
 
-To further explore the capabilities of our APIs (`4Wings`, `Vessels`, `Events`, `Insights`, `Datasets`, `References`, etc.), please refer to the detailed [Usage Guides](usage-guides/index). These guides delve into specific use cases and demonstrate how to effectively leverage the `gfw-api-python-client` for your data exploration needs.
+To further explore the capabilities of our APIs (`4Wings`, `Vessels`, `Events`, `Insights`, `Datasets`, `References`, etc.), please refer to the detailed [Usage Guides](usage-guides/index) and [Workflow Guides](workflow-guides/index). These guides delve into specific use cases and demonstrate how to effectively leverage the `gfw-api-python-client` for your data exploration needs.
 
 Happy coding and data exploring!

docs/source/index.md

@@ -14,6 +14,7 @@ The `gfw-api-python-client` simplifies access to Global Fishing Watch (GFW) data
 getting-started
 installation
 usage-guides/index
+workflow-guides/index
 ```
 
 ```{toctree}
@@ -49,6 +50,10 @@ To learn about how to use `gfw-api-python-client`, check out the following resou
     - [Insights API](usage-guides/insights-api)
     - [Datasets API](usage-guides/datasets-api)
     - [References Data API](usage-guides/references-data-api)
+- [Workflow Guides](workflow-guides/index)
+    - [Analyze apparent fishing effort in Senegalese EEZ](workflow-guides/workflow-01-analyze-apparent-fishing-effort-senegalese-eez)
+    - [Analyze apparent fishing effort in Argentinian EEZ](workflow-guides/workflow-02-analyze-apparent-fishing-effort-argentinian-eez)
+    - [Analyze a fleet in Ghanaian EEZ](workflow-guides/workflow-03-analyze-fleet-in-ghanaian-eez)
 
 If you find bugs, need help, or want to contribute, check out the following resources:
 

docs/source/usage-guides/4wings-api.md

@@ -374,7 +374,7 @@ The 4Wings API often requires specifying geographic regions. You can use the [Re
 
 ## Next Steps
 
-Explore the [Usage Guides](index) for other API resources to understand how you can combine the reporting and statistical capabilities of the 4Wings API with vessel information, event data, and more. Check out the following resources:
+Explore the [Usage Guides](index) and [Workflow Guides](../workflow-guides/index) for other API resources to understand how you can combine the reporting and statistical capabilities of the 4Wings API with vessel information, event data, and more. Check out the following resources:
 
 - [Vessels API](vessels-api)
 - [Events API](events-api)

docs/source/usage-guides/datasets-api.md

@@ -169,7 +169,7 @@ memory usage: 60.6+ KB
 
 ## Next Steps
 
-Explore the [Usage Guides](index) for other API resources. Check out the following resources:
+Explore the [Usage Guides](index) and [Workflow Guides](../workflow-guides/index) for other API resources. Check out the following resources:
 
 - [4Wings API](4wings-api)
 - [Vessels API](vessels-api)

docs/source/usage-guides/events-api.md

@@ -219,7 +219,7 @@ Please be aware that the accuracy and completeness of the event data can vary. R
 
 ## Next Steps
 
-Explore the [Usage Guides](index) for other API resources to understand how you can combine event data with information about vessels, and more. Check out the following resources:
+Explore the [Usage Guides](index) and [Workflow Guides](../workflow-guides/index) for other API resources to understand how you can combine event data with information about vessels, and more. Check out the following resources:
 
 - [4Wings API](4wings-api)
 - [Vessels API](vessels-api)

docs/source/usage-guides/insights-api.md

@@ -98,7 +98,7 @@ memory usage: 180.0+ bytes
 
 ## Next Steps
 
-Explore the [Usage Guides](index) for other API resources to understand how you can combine vessel insights with event data, vessel details, and more. Check out the following resources:
+Explore the [Usage Guides](index) and [Workflow Guides](../workflow-guides/index) for other API resources to understand how you can combine vessel insights with event data, vessel details, and more. Check out the following resources:
 
 - [Vessels API](vessels-api)
 - [Events API](events-api)

docs/source/usage-guides/references-data-api.md

@@ -178,7 +178,7 @@ memory usage: 1.4+ KB
 
 ## Next Steps
 
-Explore the [Usage Guides](index) for other API resources to understand how you can combine reference data with dynamic information about events, vessels, and more. Check out the following resources:
+Explore the [Usage Guides](index) and [Workflow Guides](../workflow-guides/index) for other API resources to understand how you can combine reference data with dynamic information about events, vessels, and more. Check out the following resources:
 
 - [4Wings API](4wings-api)
 - [Vessels API](vessels-api)

docs/source/usage-guides/vessels-api.md

@@ -198,7 +198,7 @@ memory usage: 188.0+ bytes
 
 ## Next Steps
 
-Explore the [Usage Guides](index) for other API resources to understand how you can combine vessel data with information about events, and more. Check out the following resources:
+Explore the [Usage Guides](index) and [Workflow Guides](../workflow-guides/index) for other API resources to understand how you can combine vessel data with information about events, and more. Check out the following resources:
 
 - [4Wings API](4wings-api)
 - [Events API](events-api)

docs/source/workflow-guides/index.md

@@ -0,0 +1,14 @@
+# Workflow Guides
+
+The sections below provide detailed instructions on how to combine Global Fishing Watch APIs to build powerful **workflows** and **applications** for a variety of **use cases** using the [gfw-api-python-client](https://github.com/GlobalFishingWatch/gfw-api-python-client). For additional context and expanded explanations, refer to the [API Workflows Guide (PDF)](https://globalfishingwatch.org/our-apis/assets/2025_GFW_API_Workflows.pdf), and [API Workflows](https://globalfishingwatch.org/our-apis/documentation#api-workflows) pages in the [GFW API documentation](https://globalfishingwatch.org/our-apis/documentation#introduction).
+
+
+> **Note:** See the [Datasets](https://globalfishingwatch.org/our-apis/documentation#api-dataset), [Data Caveats](https://globalfishingwatch.org/our-apis/documentation#data-caveat), and [Terms of Use](https://globalfishingwatch.org/our-apis/documentation#terms-of-use) pages in the [GFW API documentation](https://globalfishingwatch.org/our-apis/documentation#introduction) for details on GFW data, API licenses, and rate limits.
+
+```{toctree}
+:maxdepth: 1
+
+workflow-01-analyze-apparent-fishing-effort-senegalese-eez
+workflow-02-analyze-apparent-fishing-effort-argentinian-eez
+workflow-03-analyze-fleet-in-ghanaian-eez
+```