Skip to content

Commit 2f0d701

Browse files
committed
refactor(docs): improve docs interactivity ratio for RDT
1 parent fdc84df commit 2f0d701

2 files changed

Lines changed: 63 additions & 33 deletions

File tree

docs/EXAMPLES.md

Lines changed: 59 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -16,16 +16,9 @@ to name a few.
1616
!!! tip "Where’s the data at?"
1717
All the datasets powering these examples are public and ready for you to grab. Pick your channel:
1818

19-
- **Channel 1: Our Google Drive stash**
20-
- **Option A**: Snag everything in one go with this command (no fuss, no muss!):
21-
```bash
22-
# Need gdown? Install it first: brew install gdown or pip install gdown
23-
gdown https://drive.google.com/drive/folders/1n-5zkNqT97W-I9Dc7X_mG4kezskfVtlb -O ./data --folder
24-
```
25-
- **Option B**: Cherry-pick what you need manually from the [Google Drive folder](https://drive.google.com/drive/folders/1n-5zkNqT97W-I9Dc7X_mG4kezskfVtlb).
26-
- **Channel 2: Straight from the source**
19+
- **Channel 1: Straight from the source**
2720
- Check the links in each notebook, download from the official sites, and drop them into your `data/` folder.
28-
- **Channel 3: HuggingFace OSCUR datasets hub**
21+
- **Channel 2: HuggingFace OSCUR datasets hub**
2922
- If you prefer HuggingFace, you can find the datasets in the [OSCUR datasets hub](https://huggingface.co/datasets/oscur).
3023
Use the `datasets` library to load them directly into your code (integrated with `UrbanMapper`):
3124
```python
@@ -34,26 +27,60 @@ to name a few.
3427
gdf = loader.load()
3528
print(gdf.head())
3629
```
37-
38-
Once you’ve got the goods, you’re ready to roll! 🎉
39-
40-
41-
## Interactivity Table Support
42-
43-
!!! important "Some Notebooks Are Fully Interactive / Partially Interactive / Non-interactive"
44-
- **Fully Interactive**: These notebooks are fully interactive, meaning you can view the entire process from input to output directly on the documentation site.
45-
- **Partially Interactive**: These notebooks are partially interactive; while most content is visible, some components, such as maps, may not display because Material For MkDocs does not support some of Ipywidget components used in some Jupyter notebooks. However, you can find these notebooks in the `examples/` directory of the original repository and run them locally to view the full content.
46-
- **Non-interactive**: These are static notebooks that have not been executed, often because they require data or resources that were not available. For example, if certain data are needed but were not accessible on HuggingFace, we could not retrieve them. For these notebooks, we suggest cloning the repository, installing the library, and running them locally too.
47-
48-
All the notebooks mentioned can be found in the `examples/` directory of the original repository.
49-
For the partially interactive and non-interactive notebooks, running them locally will allow you to experience
50-
their full functionality.
51-
52-
See below the table 👇
53-
54-
| Category | Fully Interactive | Partially Interactive | Non-interactive | Comments |
55-
|----------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
56-
| **1-Per-Module** | <ul><li><a href="../copy_of_examples/1-Per-Module/3-imputer">Imputer</a></li><li><a href="../copy_of_examples/1-Per-Module/4-filter">Filter</a></li><li><a href="../copy_of_examples/1-Per-Module/5-enricher">Enricher</a></li><li><a href="../copy_of_examples/1-Per-Module/6-visualiser">Visualiser</a></li><li><a href="../copy_of_examples/1-Per-Module/7-urban_pipeline">Urban Pipeline</a></li></ul> | <ul><li><a href="../copy_of_examples/1-Per-Module/2-urban_layer">Urban Layer</a></li></ul> | <ul><li><a href="../copy_of_examples/1-Per-Module/1-loader">Loader</a></li><li><a href="../copy_of_examples/1-Per-Module/8-pipeline_generator">Pipeline Generator</a></li></ul> | - Non-interactive: Require specific data or setup not available in the documentation environment.<br>- Partially interactive: Some cells require local files not available on HuggingFace or others. |
57-
| **2-End-to-End** | <ul><li><a href="../copy_of_examples/2-End-to-End/1-step_by_step">Step by Step</a></li><li><a href="../copy_of_examples/2-End-to-End/2-pipeline_way">Pipeline Way</a></li></ul> | | | |
58-
| **3-Case-Studies** | <ul><li><a href="../copy_of_examples/3-Case-Studies/1-Downtown-BK-Collisions/1-Downtown_BK_Collisions_StepByStep">Downtown BK Collisions - Step by Step</a></li><li><a href="../copy_of_examples/3-Case-Studies/1-Downtown-BK-Collisions/2-Downtown_BK_Collisions_Pipeline">Downtown BK Collisions - Pipeline</a></li></ul> | <ul><li><a href="../copy_of_examples/3-Case-Studies/2-Downtown-BK-Taxi-Trips/1-Downtown_BK_Taxi_Trips_StepByStep">Downtown BK Taxi Trips - Step by Step</a></li><li><a href="../copy_of_examples/3-Case-Studies/2-Downtown-BK-Taxi-Trips/2-Downtown_BK_Taxi_Trips_Pipeline">Downtown BK Taxi Trips - Pipeline</a></li></ul> | <ul><li><a href="../copy_of_examples/3-Case-Studies/3-Europe-Restaurants/1-EU_Restaurants_Pipeline">EU Restaurants Pipeline</a></li><li><a href="../copy_of_examples/3-Case-Studies/4-Paris-Remarkable-Trees/1-Paris_Remarquable_Trees_Pipeline">Paris Remarkable Trees - Pipeline</a></li><li><a href="../copy_of_examples/3-Case-Studies/5-Overture-instead-of-OSM/1-overture_pipeline">Overture Pipeline</a></li><li><a href="../copy_of_examples/3-Case-Studies/1-Downtown-BK-Collisions/3-Downtown_BK_Collisions_Advanced_Pipeline">Downtown BK Collisions - Advanced Pipeline</a></li><li><a href="../copy_of_examples/3-Case-Studies/1-Downtown-BK-Collisions/4-Downtown_BK_Collisions_Advanced_Pipeline_Extras">Downtown BK Collisions - Advanced Pipeline Extras</a></li><li><a href="../copy_of_examples/3-Case-Studies/2-Downtown-BK-Taxi-Trips/3-Downtown_BK_Taxi_Trips_Advanced_Pipeline">Downtown BK Taxi Trips - Advanced Pipeline</a></li><li><a href="../copy_of_examples/3-Case-Studies/2-Downtown-BK-Taxi-Trips/4-Downtown_BK_Taxi_Trips_Advanced_Pipeline_Extras">Downtown BK Taxi Trips - Advanced Pipeline Extras</a></li><li><a href="../copy_of_examples/3-Case-Studies/4-Paris-Remarkable-Trees/2-Paris_Remarquable_Trees_Advanced_Pipeline">Paris Remarkable Trees - Advanced Pipeline</a></li><li><a href="../copy_of_examples/3-Case-Studies/5-Overture-instead-of-OSM/2-overture_pipeline_advanced">Advanced Overture Pipeline</a></li></ul> | - EU Restaurants, Paris Remarkable Trees - Pipeline, Overture Pipeline: Require specific data not available on HuggingFace.<br>- All Advanced Pipelines: Too resource-intensive to run in documentation or locally.<br>- Partially interactive items require ipywidgets, which are not supported by material for mkdocs. |
59-
| **4-External-Libraries-Usages** | <ul><li><a href="../copy_of_examples/4-External-Libraries-Usages/2-interactive_table_vis">Interactive Table VIS</a></li></ul> | | <ul><li><a href="../copy_of_examples/4-External-Libraries-Usages/1-auctus_search">Auctus Search</a></li><li><a href="../copy_of_examples/4-External-Libraries-Usages/3-jupyter_gis_multi_pipeline/1-one_pipeline">Jupyter GIS Multi Pipeline - One Pipeline</a></li><li><a href="../copy_of_examples/4-External-Libraries-Usages/3-jupyter_gis_multi_pipeline/2-two_pipeline">Jupyter GIS Multi Pipeline - Two Pipeline</a></li><li><a href="../copy_of_examples/4-External-Libraries-Usages/3-jupyter_gis_multi_pipeline/3-three_pipeline">Jupyter GIS Multi Pipeline - Three Pipeline</a></li></ul> | Non-interactive due to requiring external resources or specific data not accessible in the documentation environment. Furthermore, JGIS is not yet supported in material for MKDocs. |
30+
31+
## Execution Status at a Glance
32+
33+
!!! info "A quick heads-up on execution"
34+
Notebooks are either executed in the docs or kept as static previews. If you want the full interactive experience,
35+
run them locally from the `examples/` folder in the repository.
36+
37+
=== "▶️ Executed in docs"
38+
39+
**2-End-to-End**
40+
41+
- [Pipeline Way](../copy_of_examples/2-End-to-End/2-pipeline_way)
42+
43+
=== "🧊 Not executed in docs"
44+
These render as static previews. Run locally for full outputs.
45+
46+
**1-Per-Module**
47+
48+
- [Loader](../copy_of_examples/1-Per-Module/1-loader)
49+
- [Urban Layer](../copy_of_examples/1-Per-Module/2-urban_layer)
50+
- [Imputer](../copy_of_examples/1-Per-Module/3-imputer)
51+
- [Filter](../copy_of_examples/1-Per-Module/4-filter)
52+
- [Enricher](../copy_of_examples/1-Per-Module/5-enricher)
53+
- [Visualiser](../copy_of_examples/1-Per-Module/6-visualiser)
54+
- [urban pipeline](../copy_of_examples/1-Per-Module/7-urban_pipeline)
55+
- [Pipeline Generator](../copy_of_examples/1-Per-Module/8-pipeline_generator)
56+
57+
**2-End-to-End**
58+
- [Step by Step](../copy_of_examples/2-End-to-End/1-step_by_step)
59+
60+
**3-Case-Studies**
61+
62+
- [Downtown BK Collisions - Step by Step](../copy_of_examples/3-Case-Studies/1-Downtown-BK-Collisions/1-Downtown_BK_Collisions_StepByStep)
63+
- [Downtown BK Collisions - Pipeline](../copy_of_examples/3-Case-Studies/1-Downtown-BK-Collisions/2-Downtown_BK_Collisions_Pipeline)
64+
- [Downtown BK Collisions - Advanced Pipeline](../copy_of_examples/3-Case-Studies/1-Downtown-BK-Collisions/3-Downtown_BK_Collisions_Advanced_Pipeline)
65+
- [Downtown BK Collisions - Advanced Pipeline Extras](../copy_of_examples/3-Case-Studies/1-Downtown-BK-Collisions/4-Downtown_BK_Collisions_Advanced_Pipeline_Extras)
66+
- [Downtown BK Taxi Trips - Step by Step](../copy_of_examples/3-Case-Studies/2-Downtown-BK-Taxi-Trips/1-Downtown_BK_Taxi_Trips_StepByStep)
67+
- [Downtown BK Taxi Trips - Pipeline](../copy_of_examples/3-Case-Studies/2-Downtown-BK-Taxi-Trips/2-Downtown_BK_Taxi_Trips_Pipeline)
68+
- [Downtown BK Taxi Trips - Advanced Pipeline](../copy_of_examples/3-Case-Studies/2-Downtown-BK-Taxi-Trips/3-Downtown_BK_Taxi_Trips_Advanced_Pipeline)
69+
- [Downtown BK Taxi Trips - Advanced Pipeline Extras](../copy_of_examples/3-Case-Studies/2-Downtown-BK-Taxi-Trips/4-Downtown_BK_Taxi_Trips_Advanced_Pipeline_Extras)
70+
- [EU Restaurants Pipeline](../copy_of_examples/3-Case-Studies/3-Europe-Restaurants/1-EU_Restaurants_Pipeline)
71+
- [Paris Remarkable Trees - Pipeline](../copy_of_examples/3-Case-Studies/4-Paris-Remarkable-Trees/1-Paris_Remarquable_Trees_Pipeline)
72+
- [Paris Remarkable Trees - Advanced Pipeline](../copy_of_examples/3-Case-Studies/4-Paris-Remarkable-Trees/2-Paris_Remarquable_Trees_Advanced_Pipeline)
73+
- [Overture Pipeline](../copy_of_examples/3-Case-Studies/5-Overture-instead-of-OSM/1-overture_pipeline)
74+
- [Advanced Overture Pipeline](../copy_of_examples/3-Case-Studies/5-Overture-instead-of-OSM/2-overture_pipeline_advanced)
75+
76+
**4-External-Libraries-Usages**
77+
78+
- [Auctus Search](../copy_of_examples/4-External-Libraries-Usages/1-auctus_search)
79+
- [Interactive Table VIS](../copy_of_examples/4-External-Libraries-Usages/2-interactive_table_vis)
80+
- [Jupyter GIS Multi Pipeline - One Pipeline](../copy_of_examples/4-External-Libraries-Usages/3-jupyter_gis_multi_pipeline/1-one_pipeline)
81+
- [Jupyter GIS Multi Pipeline - Two Pipeline](../copy_of_examples/4-External-Libraries-Usages/3-jupyter_gis_multi_pipeline/2-two_pipeline)
82+
- [Jupyter GIS Multi Pipeline - Three Pipeline](../copy_of_examples/4-External-Libraries-Usages/3-jupyter_gis_multi_pipeline/3-three_pipeline)
83+
84+
!!! tip "Want the full interactive experience?"
85+
Clone the repo, pull the datasets, and run any notebook locally from `examples/`. Most notebooks contain links to
86+
their data sources or instructions in the first few cells.

mkdocs.yml

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -95,11 +95,14 @@ plugins:
9595
execute: true
9696
execute_ignore:
9797
- "copy_of_examples/1-Per-Module/1-loader.ipynb"
98+
- "copy_of_examples/1-Per-Module/2-urban_layer.ipynb"
9899
- "copy_of_examples/1-Per-Module/3-imputer.ipynb"
99100
- "copy_of_examples/1-Per-Module/4-filter.ipynb"
100101
- "copy_of_examples/1-Per-Module/5-enricher.ipynb"
101102
- "copy_of_examples/1-Per-Module/6-visualiser.ipynb"
103+
- "copy_of_examples/1-Per-Module/7-urban_pipeline.ipynb"
102104
- "copy_of_examples/1-Per-Module/8-pipeline_generator.ipynb"
105+
- "copy_of_examples/2-End-to-End/1-step_by_step.ipynb"
103106
- "copy_of_examples/3-Case-Studies/1-Downtown-BK-Collisions/1-Downtown_BK_Collisions_StepByStep.ipynb"
104107
- "copy_of_examples/3-Case-Studies/1-Downtown-BK-Collisions/2-Downtown_BK_Collisions_Pipeline.ipynb"
105108
- "copy_of_examples/3-Case-Studies/1-Downtown-BK-Collisions/3-Downtown_BK_Collisions_Advanced_Pipeline.ipynb"
@@ -158,7 +161,7 @@ nav:
158161
- Installation: getting-started/installation.md
159162
- Getting Started Step-By-Step: getting-started/quick-start_step_by_step.md
160163
- Getting Started W/ Pipeline: getting-started/quick-start_pipeline.md
161-
- Interactive Examples:
164+
- Examples:
162165
- Overview: EXAMPLES.md
163166
- Per-Module Examples:
164167
- "Loader": copy_of_examples/1-Per-Module/1-loader.ipynb

0 commit comments

Comments
 (0)