Automatic list with overviews of inlcuded area definitions for the documentation

.gitignore

@@ -75,6 +75,7 @@ doc/source/_build/*
 satpy/version.py
 doc/source/api/*.rst
 doc/source/reader_table.rst
+doc/source/area_def_list.rst
 
 # lock files
 *.lock

doc/rtd_environment.yml

@@ -31,6 +31,7 @@ dependencies:
   - xarray
   - zarr
   - xarray-datatree
+  - cartopy
   - pip:
     - graphviz
     - pytest-lazy-fixtures

doc/source/_static/main.js

@@ -8,4 +8,15 @@ $(document).ready( function () {
     },
     "order": [[0, 'asc']]
 } );
+
+    $('table.area-table').DataTable( {
+    "paging": true,
+    "pageLength": 15,
+    "layout": {
+        'topStart': 'info',
+        'topEnd': 'search',
+        'bottomEnd': 'paging',
+        'bottomStart': null
+    }
+} );
 } );

doc/source/conf.py

@@ -24,9 +24,15 @@
 sys.path.append(os.path.abspath("../../"))
 sys.path.append(os.path.abspath(os.path.dirname(__file__)))
 
-from reader_table import generate_reader_table  # noqa: E402
+from pyresample.area_config import (  # noqa: E402
+    _create_area_def_from_dict,
+    _read_yaml_area_file_content,
+    generate_area_def_rst_list,
+)
+from reader_table import generate_reader_table, rst_table_header, rst_table_row  # noqa: E402
 
 import satpy  # noqa: E402
+from satpy.resample import get_area_file  # noqa: E402
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -80,6 +86,26 @@ def __getattr__(cls, name):
 with open("reader_table.rst", mode="w") as f:
     f.write(generate_reader_table())
 
+# create table from area definition yaml file
+area_file = get_area_file()[0]
+
+area_dict = _read_yaml_area_file_content(area_file)
+area_table = [rst_table_header("Area Definitions", header=["Name", "Description", "Projection"],
+                               widths="auto", class_name="area-table")]
+
+for aname, params in area_dict.items():
+    area = _create_area_def_from_dict(aname, params)
+    if not hasattr(area, "_repr_html_"):
+        continue
+
+    area_table.append(rst_table_row([f"`{aname}`_", area.description,
+                                     area.proj_dict.get("proj")]))
+
+with open("area_def_list.rst", mode="w") as f:
+    f.write("".join(area_table))
+    f.write("\n\n")
+    f.write(generate_area_def_rst_list(area_file))
+
 # -- General configuration -----------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
@@ -194,11 +220,13 @@ def __getattr__(cls, name):
 
 html_css_files = [
     "theme_overrides.css",  # override wide tables in RTD theme
-    "https://cdn.datatables.net/v/dt/dt-2.0.0/datatables.min.css",
+    # "https://cdn.datatables.net/v/dt/dt-2.0.0/datatables.min.css",
+    "https://cdn.datatables.net/v/dt/dt-2.0.8/r-3.0.2/datatables.min.css"
 ]
 
 html_js_files = [
-    "https://cdn.datatables.net/v/dt/dt-2.0.0/datatables.min.js",
+    # "https://cdn.datatables.net/v/dt/dt-2.0.0/datatables.min.js",
+    "https://cdn.datatables.net/v/dt/dt-2.0.8/r-3.0.2/datatables.min.js",
     "main.js",
 ]
 

doc/source/reader_table.py

@@ -39,29 +39,31 @@
     return row
 
 
-def rst_table_header(name=None, header=None, header_rows=1, widths="auto"):  # noqa: D417
+def rst_table_header(name=None, header=None, header_rows=1, widths="auto", class_name="datatable"):
     """Create header for rst table.
 
     Args:
         name (str): Name of the table
         header (list[str]): Column names
-        header-rows (int): Number of header rows
-        width (optional[list[int]]): Width of each column as a list. If not specified
+        header_rows (int): Number of header rows
+        widths (optional[list[int]]): Width of each column as a list. If not specified
             defaults to auto and will therefore determined by the backend
             (see <https://docutils.sourceforge.io/docs/ref/rst/directives.html#table>)
+        class_name (str): The CSS class name for the table. A corresponding js function should be in main.js in
+            in the "statis" directory.
 
     Returns:
         str
     """
     if isinstance(widths, list):
         widths = " ".join([str(w) for w in widths])
 
     header = rst_table_row(header)
 
     table_header = (f".. list-table:: {name}\n"
                     f"    :header-rows: {header_rows}\n"
                     f"    :widths: {widths}\n"
-                    f"    :class: datatable\n\n"
+                    f"    :class: {class_name}\n\n"
                     f"{header}")
 
     return table_header
@@ -74,7 +76,7 @@
         str
     """
     table = [rst_table_header("Satpy Readers", header=["Description", "Reader name", "Status", "fsspec support"],
-                              widths=[45, 25, 30, 30])]
+                              widths="auto")]
 
     reader_configs = available_readers(as_dict=True, yaml_loader=BaseLoader)
     for rc in reader_configs: