diff --git a/ci/docs.yml b/ci/docs.yml index 7d5c15e54..b5138fdcb 100644 --- a/ci/docs.yml +++ b/ci/docs.yml @@ -19,6 +19,7 @@ dependencies: - jupyter_client - scikit-learn - sphinx-book-theme + - sphinx-autosummary-accessors - myst-nb - sphinx-design - nbsphinx diff --git a/docs/conf.py b/docs/conf.py index af911fcfd..c2c886636 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -10,6 +10,7 @@ import pathlib import yaml from sphinx.application import Sphinx +import sphinx_autosummary_accessors from sphinx.util import logging from textwrap import dedent, indent import datetime @@ -49,6 +50,7 @@ def __getattr__(cls, name): "sphinx.ext.autosummary", "sphinx.ext.intersphinx", "sphinx.ext.mathjax", + "sphinx_autosummary_accessors", "myst_nb", "sphinx_design", "nbsphinx", @@ -98,7 +100,7 @@ def __getattr__(cls, name): autosummary_generate = True # Add any paths that contain templates here, relative to this directory. -templates_path = ["_templates"] +templates_path = ["_templates", sphinx_autosummary_accessors.templates_path] # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: diff --git a/docs/internal_api/index.rst b/docs/internal_api/index.rst index bfa899f5b..2b8bda157 100644 --- a/docs/internal_api/index.rst +++ b/docs/internal_api/index.rst @@ -19,7 +19,7 @@ features explicitly added to work on Unstructured Grids. Class ----- .. autosummary:: - :toctree: _autosummary + :toctree: generated/ UxDataset @@ -27,7 +27,7 @@ Class Attributes ---------- .. autosummary:: - :toctree: _autosummary + :toctree: generated/ UxDataset._source_datasets UxDataset._uxgrid @@ -35,7 +35,7 @@ Attributes Methods ------- .. autosummary:: - :toctree: _autosummary + :toctree: generated/ UxDataset.__getitem__ UxDataset.__setitem__ @@ -55,21 +55,21 @@ features explicitly added to work on Unstructured Grids. Class ----- .. autosummary:: - :toctree: _autosummary + :toctree: generated/ UxDataArray Attributes ---------- .. autosummary:: - :toctree: _autosummary + :toctree: generated/ UxDataArray._uxgrid Methods ------- .. autosummary:: - :toctree: _autosummary + :toctree: generated/ UxDataArray._construct_direct UxDataArray._copy @@ -84,14 +84,14 @@ Grid Class ----- .. autosummary:: - :toctree: _autosummary + :toctree: generated/ Grid Operators --------- .. autosummary:: - :toctree: _autosummary + :toctree: generated/ Grid.__eq__ Grid.__ne__ @@ -103,7 +103,7 @@ Helpers Connectivity ------------ .. autosummary:: - :toctree: _autosummary + :toctree: generated/ grid.connectivity._face_nodes_to_sparse_matrix grid.connectivity._replace_fill_values @@ -121,7 +121,7 @@ Connectivity Geometry -------- .. autosummary:: - :toctree: _autosummary + :toctree: generated/ grid.geometry._pad_closed_face_nodes grid.geometry._build_polygon_shells grid.geometry._grid_to_polygon_geodataframe @@ -140,7 +140,7 @@ Geometry Coordinates ----------- .. autosummary:: - :toctree: _autosummary + :toctree: generated/ grid.coordinates._get_lonlat_from_xyz grid.coordinates._get_xyz_from_lonlat @@ -154,7 +154,7 @@ Coordinates Arcs ---- .. autosummary:: - :toctree: _autosummary + :toctree: generated/ grid.arcs._angle_of_2_vectors grid.arcs._angle_of_2_vectors @@ -163,7 +163,7 @@ Arcs Utils ----- .. autosummary:: - :toctree: _autosummary + :toctree: generated/ grid.utils._newton_raphson_solver_for_gca_constLat grid.utils._inv_jacobian @@ -174,7 +174,7 @@ Utils Validation ---------- .. autosummary:: - :toctree: _autosummary + :toctree: generated/ grid.validation._check_connectivity grid.validation._check_duplicate_nodes @@ -183,7 +183,7 @@ Validation Accurate Computing Utils ------------------------ .. autosummary:: - :toctree: _autosummary + :toctree: generated/ utils.computing._err_fmac utils.computing._fast_two_mult @@ -204,7 +204,7 @@ Remapping ========= .. autosummary:: - :toctree: _autosummary + :toctree: generated/ remap.nearest_neighbor._nearest_neighbor remap.nearest_neighbor._nearest_neighbor_uxda @@ -217,7 +217,7 @@ Grid Parsing and Encoding UGRID ----- .. autosummary:: - :toctree: _autosummary + :toctree: generated/ io._ugrid._read_ugrid io._ugrid._encode_ugrid @@ -228,7 +228,7 @@ UGRID MPAS ---- .. autosummary:: - :toctree: _autosummary + :toctree: generated/ io._mpas._read_mpas io._mpas._primal_to_ugrid @@ -242,7 +242,7 @@ MPAS Exodus --------- .. autosummary:: - :toctree: _autosummary + :toctree: generated/ io._exodus._read_exodus io._exodus._encode_exodus @@ -251,7 +251,7 @@ Exodus SCRIP ----- .. autosummary:: - :toctree: _autosummary + :toctree: generated/ io._scrip._to_ugrid io._scrip._read_scrip @@ -261,28 +261,28 @@ SCRIP Shapefile --------- .. autosummary:: - :toctree: _autosummary + :toctree: generated/ io._shapefile._read_shpfile Vertices -------- .. autosummary:: - :toctree: _autosummary + :toctree: generated/ io._vertices._read_face_vertices Utils ----- .. autosummary:: - :toctree: _autosummary + :toctree: generated/ io.utils._parse_grid_type Core Utils ---------- .. autosummary:: - :toctree: _autosummary + :toctree: generated/ core.utils._map_dims_to_ugrid @@ -290,7 +290,7 @@ Core Utils Visualization ------------- .. autosummary:: - :toctree: _autosummary + :toctree: generated/ plot.grid_plot._plot_coords_as_points plot.dataarray_plot._plot_data_as_points @@ -300,7 +300,7 @@ Visualization Slicing ------- .. autosummary:: - :toctree: _autosummary + :toctree: generated/ grid.slice._slice_node_indices grid._slice_edge_indices @@ -311,7 +311,7 @@ Slicing Subsetting ---------- .. autosummary:: - :toctree: _autosummary + :toctree: generated/ subset.grid_accessor.GridSubsetAccessor subset.dataarray_accessor.DataArraySubsetAccessor diff --git a/docs/user_api/index.rst b/docs/user_api/index.rst index 9a50189ef..8023b154b 100644 --- a/docs/user_api/index.rst +++ b/docs/user_api/index.rst @@ -22,14 +22,14 @@ Unstructured Grids: Class ----- .. autosummary:: - :toctree: _autosummary + :toctree: generated/ UxDataset IO -- .. autosummary:: - :toctree: _autosummary + :toctree: generated/ open_dataset open_mfdataset @@ -37,7 +37,7 @@ IO Attributes ---------- .. autosummary:: - :toctree: _autosummary + :toctree: generated/ UxDataset.uxgrid UxDataset.source_datasets @@ -45,7 +45,7 @@ Attributes Methods ------- .. autosummary:: - :toctree: _autosummary + :toctree: generated/ UxDataset.info UxDataset.integrate @@ -54,14 +54,15 @@ Methods Remapping --------- .. autosummary:: - :toctree: _autosummary + :toctree: generated/ UxDataset.nearest_neighbor_remap Plotting -------- .. autosummary:: - :toctree: _autosummary + :toctree: generated/ + :template: autosummary/accessor.rst UxDataset.plot @@ -81,14 +82,14 @@ Unstructured Grids: Class ----- .. autosummary:: - :toctree: _autosummary + :toctree: generated/ UxDataArray IO -- .. autosummary:: - :toctree: _autosummary + :toctree: generated/ UxDataArray.to_dataset UxDataArray.to_geodataframe @@ -98,13 +99,14 @@ IO Attributes ---------- .. autosummary:: - :toctree: _autosummary + :toctree: generated/ + UxDataArray.uxgrid Methods ------- .. autosummary:: - :toctree: _autosummary + :toctree: generated/ UxDataArray.integrate UxDataArray.isel @@ -113,7 +115,7 @@ Methods Remapping --------- .. autosummary:: - :toctree: _autosummary + :toctree: generated/ UxDataArray.nearest_neighbor_remap UxDataArray.nodal_average @@ -121,9 +123,15 @@ Remapping Plotting -------- .. autosummary:: - :toctree: _autosummary + :toctree: generated/ + :template: autosummary/accessor.rst UxDataArray.plot + +.. autosummary:: + :toctree: generated/ + :template: autosummary/accessor_method.rst + UxDataArray.plot.datashade UxDataArray.plot.rasterize UxDataArray.plot.polygons @@ -132,9 +140,15 @@ Plotting Subsetting ---------- .. autosummary:: - :toctree: _autosummary + :toctree: generated/ + :template: autosummary/accessor.rst UxDataArray.subset + +.. autosummary:: + :toctree: generated/ + :template: autosummary/accessor_method.rst + UxDataArray.subset.nearest_neighbor UxDataArray.subset.bounding_circle UxDataArray.subset.bounding_box @@ -153,14 +167,14 @@ them unstructured grid-aware data sets and arrays. Class ----- .. autosummary:: - :toctree: _autosummary + :toctree: generated/ Grid IO -- .. autosummary:: - :toctree: _autosummary + :toctree: generated/ open_grid Grid.from_dataset @@ -174,7 +188,7 @@ IO Methods ------- .. autosummary:: - :toctree: _autosummary + :toctree: generated/ Grid.calculate_total_face_area Grid.compute_face_areas @@ -188,7 +202,7 @@ Methods Dimensions ---------- .. autosummary:: - :toctree: _autosummary + :toctree: generated/ Grid.n_node Grid.n_edge @@ -200,7 +214,7 @@ Dimensions Spherical Coordinates --------------------- .. autosummary:: - :toctree: _autosummary + :toctree: generated/ Grid.node_lon Grid.node_lat @@ -212,7 +226,7 @@ Spherical Coordinates Cartesian Coordinates --------------------- .. autosummary:: - :toctree: _autosummary + :toctree: generated/ Grid.node_x Grid.node_y @@ -227,7 +241,7 @@ Cartesian Coordinates Connectivity ------------ .. autosummary:: - :toctree: _autosummary + :toctree: generated/ Grid.face_node_connectivity Grid.edge_node_connectivity @@ -242,7 +256,7 @@ Connectivity Grid Descriptors ---------------- .. autosummary:: - :toctree: _autosummary + :toctree: generated/ Grid.face_areas Grid.antimeridian_face_indices @@ -251,7 +265,7 @@ Grid Descriptors Attributes ---------- .. autosummary:: - :toctree: _autosummary + :toctree: generated/ Grid.grid_spec Grid.parsed_attrs @@ -260,9 +274,15 @@ Attributes Plotting -------- .. autosummary:: - :toctree: _autosummary + :toctree: generated/ + :template: autosummary/accessor.rst Grid.plot + +.. autosummary:: + :toctree: generated/ + :template: autosummary/accessor_method.rst + Grid.plot.node_coords Grid.plot.nodes Grid.plot.face_coords @@ -275,53 +295,18 @@ Plotting Subsetting ---------- .. autosummary:: - :toctree: _autosummary + :toctree: generated/ + :template: autosummary/accessor.rst Grid.subset - Grid.subset.nearest_neighbor - Grid.subset.bounding_circle - Grid.subset.bounding_box - - - -Visualization -============= - -Accessors ---------- -.. autosummary:: - :toctree: _autosummary - - plot.accessor.GridPlotAccessor - plot.accessor.UxDataArrayPlotAccessor - plot.accessor.UxDatasetPlotAccessor - -Grid Plotting Methods ---------------------- .. autosummary:: - :toctree: _autosummary - - plot.grid_plot.mesh - plot.grid_plot.edges - plot.grid_plot.node_coords - plot.grid_plot.nodes - plot.grid_plot.face_coords - plot.grid_plot.face_centers - plot.grid_plot.edge_coords - plot.grid_plot.edge_centers - - -UxDataArray Plotting Methods ----------------------------- -.. autosummary:: - :toctree: _autosummary - - plot.dataarray_plot.datashade - plot.dataarray_plot.rasterize - plot.dataarray_plot.polygons - plot.dataarray_plot.points + :toctree: generated/ + :template: autosummary/accessor_method.rst + Grid.subset.nearest_neighbor + Grid.subset.bounding_circle + Grid.subset.bounding_box Nearest Neighbor Data Structures @@ -330,7 +315,7 @@ Nearest Neighbor Data Structures KDTree ------ .. autosummary:: - :toctree: _autosummary + :toctree: generated/ grid.neighbors.KDTree grid.neighbors.KDTree.query @@ -339,7 +324,7 @@ KDTree BallTree -------- .. autosummary:: - :toctree: _autosummary + :toctree: generated/ grid.neighbors.BallTree grid.neighbors.BallTree.query @@ -352,7 +337,7 @@ Helpers Face Area ---------- .. autosummary:: - :toctree: _autosummary + :toctree: generated/ grid.area.calculate_face_area grid.area.get_all_face_area_from_coords @@ -364,14 +349,14 @@ Face Area Connectivity ------------ .. autosummary:: - :toctree: _autosummary + :toctree: generated/ grid.connectivity.close_face_nodes Coordinates ----------- .. autosummary:: - :toctree: _autosummary + :toctree: generated/ grid.coordinates.node_lonlat_rad_to_xyz grid.coordinates.node_xyz_to_lonlat_rad @@ -381,7 +366,7 @@ Coordinates Arcs ---- .. autosummary:: - :toctree: _autosummary + :toctree: generated/ grid.arcs.in_between grid.arcs.point_within_gca @@ -390,7 +375,7 @@ Arcs Intersections ------------- .. autosummary:: - :toctree: _autosummary + :toctree: generated/ grid.intersections.gca_gca_intersection grid.intersections.gca_constLat_intersection @@ -398,7 +383,7 @@ Intersections Accurate Computing Utils ----- .. autosummary:: - :toctree: _autosummary + :toctree: generated/ utils.computing.cross_fma utils.computing.dot_fma @@ -406,7 +391,7 @@ Accurate Computing Utils Numba ----- .. autosummary:: - :toctree: _autosummary + :toctree: generated/ utils.enable_jit_cache utils.disable_jit_cache