Doc: Python: add executable examples using myst-nb

doc/requirements.txt

@@ -11,3 +11,4 @@ recommonmark
 sphinx-markdown-tables
 sphinxcontrib-spelling
 sphinxcontrib-jquery
+myst_nb

doc/source/api/python/index.rst

@@ -10,6 +10,7 @@ Python API
        :maxdepth: 2
 
        python_bindings
+       python_examples
        osgeo
        raster_api
        vector_api

doc/source/api/python/python_examples.myst

@@ -0,0 +1,94 @@
+---
+jupytext:
+  formats: md:myst
+  text_representation:
+    extension: .md
+    format_name: myst
+kernelspec:
+  display_name: Python 3
+  language: python
+  name: python3
+---
+
+# Examples
+
+## Getting information on a raster dataset using dedicated methods
+
+The following snippet uses individual API methods to retrieve characters of
+a GDAL raster dataset and its bands.
+
+```{code-cell}
+
+from osgeo import gdal
+import json
+
+gdal.UseExceptions()
+
+with gdal.Open("data/byte.tif") as ds:
+    print(f"Width: {ds.RasterXSize}")
+    print(f"Height: {ds.RasterYSize}")
+    print(f"Number of bands: {ds.RasterCount}")
+    print(f"Metadata: {ds.GetMetadata()}")
+    srs = ds.GetSpatialRef()
+    if srs:
+        srs_as_projjson = json.loads(srs.ExportToPROJJSON())
+        print("SRS:")
+        name = srs_as_projjson["name"]
+        print(f"  Name: {name}")
+        if "id" in srs_as_projjson:
+            id = srs_as_projjson["id"]
+            authority = id["authority"]
+            code = id["code"]
+            print(f"  Id: {authority}:{code}")
+    geotransform = ds.GetGeoTransform()
+    if geotransform[2] == 0 and geotransform[4] == 0:
+        print(f"Upper-left corner georeferenced position: X={geotransform[0]}, Y={geotransform[1]}")
+        print(f"Horizontal resolution: {geotransform[1]}")
+        print(f"Vertical resolution: {geotransform[5]} (if negative, indicates a north-up image)")
+    else:
+        print(f"Geotransformation matrix: {geotransform}")
+    for idx, band in enumerate(ds):
+        print(f"Band {idx+1}:")
+        print(f"  Data type: {gdal.GetDataTypeName(band.DataType)}")
+        block_width, block_height = band.GetBlockSize()
+        print(f"  Block width: {block_width}")
+        print(f"  Block height: {block_height}")
+        print(f"  Metadata: {band.GetMetadata()}")
+```
+
+## Getting information on a raster dataset using gdal.Info()
+
+The following snippet uses the {py:func}`osgeo.gdal.Info()` method to retrieve characters of
+a GDAL raster dataset and its bands, as a JSON document.
+
+```{code-cell}
+:tags: [hide-output]
+
+from osgeo import gdal
+import pprint
+
+gdal.UseExceptions()
+
+with gdal.Open("data/byte.tif") as ds:
+    info = gdal.Info(ds, format='json')
+    del info["stac"]  # to avoid cluttering below output
+    pprint.pprint(info, indent=2, width=100)
+```
+
+## Reading a whole raster as a numpy array
+
+The following snippet uses the {py:func}`osgeo.gdal.Dataset.ReadAsArray()`
+method to retrieve the pixel values of all the bands of a dataset as a
+[numpy array](https://numpy.org/doc/stable/reference/generated/numpy.array.html).
+
+```{code-cell}
+:tags: [hide-output]
+
+from osgeo import gdal
+
+gdal.UseExceptions()
+
+with gdal.Open("data/byte.tif") as ds:
+    array = ds.ReadAsArray()
+    print(array)
+```

doc/source/conf.py

@@ -72,6 +72,7 @@
     "sphinx.ext.napoleon",
     "sphinxcontrib.jquery",
     "sphinxcontrib.spelling",
+    "myst_nb",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -84,6 +85,7 @@
     "substitutions.rst",
     "programs/options/*.rst",
     "api/python/modules.rst",
+    "gdal_rtd/README.md",
 ]
 
 # Prevents double hyphen (--) to be replaced by Unicode long dash character
@@ -112,6 +114,12 @@
 .. |offline-download| replace:: {offline_download_text}
 """
 
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".ipynb": "myst-nb",
+    ".myst": "myst-nb",
+}
+
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for