Merge pull request #14 from bcdev/forman-update_api_docs

Update API docs

Author: forman

CHANGES.md

@@ -1,5 +1,9 @@
 # XRLint Change History
 
+## Version 0.2.0 (in development)
+
+- Make all docstrings comply to google-style
+
 ## Version 0.1.0 (09.01.2025)
 
 - Added CLI option `--print-config PATH`, see same option in ESLint

README.md

@@ -9,7 +9,7 @@
 
 XRLint is a [linting](https://en.wikipedia.org/wiki/Lint_(software)) 
 tool and library for [xarray]() datasets.
-Its design is heavily inspired by [ESLint](https://eslint.org/).
+Its design is heavily inspired by the awesome [ESLint](https://eslint.org/).
 
 
 ## Features 
@@ -23,13 +23,13 @@ Its design is heavily inspired by [ESLint](https://eslint.org/).
 
 ## Inbuilt Rules
 
-The following rule plugins are currently built into the code base:
+The following plugins provide XRLint's [inbuilt rules](https://bcdev.github.io/xrlint/rule-ref/):
 
-- `xrlint.plugins.core`: Implementing the rules for
+- `xrlint.plugins.core`: implementing the rules for
   [tidy data](https://tutorial.xarray.dev/intermediate/data_cleaning/05.1_intro.html)
   and the 
   [CF-Conventions](https://cfconventions.org/cf-conventions/cf-conventions.html).
-- `xrlint.plugins.core`: Implementing the rules for 
+- `xrlint.plugins.core`: implementing the rules for 
   [xcube datasets](https://xcube.readthedocs.io/en/latest/cubespec.html).
   Note, this plugin is fully optional. You must manually configure 
   it to apply its rules. It may be moved into a separate GitHub repo 

docs/api.md

@@ -1,84 +1,95 @@
 # Python API
 
-All described objects can be imported from the `xrlint.all` module.
-
-## Class `XRLint`
-
+This chapter provides a plain reference for the XRLint Python API.
+
+## Overview
+
+- The top-level API component is the class [XRLint][xrlint.cli.engine.XRLint]
+  which encapsulates the functionality of the [XRLint CLI](cli.md).
+- The `linter` module provides the functionality for linting a single 
+  dataset:
+  [new_linter()][xrlint.linter.new_linter] factory function and the
+  [Linter][xrlint.linter.Linter] class.
+- The `plugin` module provides plugin related classes:
+  [Plugin][xrlint.plugin.Plugin] and its 
+  metadata [PluginMeta][xrlint.plugin.PluginMeta].
+- The `config` module provides classes that represent 
+  configuration information and provide related functionality:
+  [Config][xrlint.config.Config] and [ConfigList][xrlint.config.ConfigList].
+- The `rule` module provides rule related classes:
+  [Rule][xrlint.rule.Rule] comprising rule metadata 
+  [RuleMeta][xrlint.rule.RuleMeta] and the rule operation 
+  [RuleOp][xrlint.rule.RuleOp], as well as related to the latter
+  [RuleContext][xrlint.rule.RuleContext] and [RuleExit][xrlint.rule.RuleExit].
+- The `node` module defines the nodes passed to [xrlint.rule.RuleOp]:
+  base classes [None][xrlint.node.Node], [XarrayNode][xrlint.node.XarrayNode]
+  and the specific [DatasetNode][xrlint.node.DatasetNode],
+  [DataArray][xrlint.node.DataArrayNode], [AttrsNode][xrlint.node.AttrsNode], 
+  and [AttrNode][xrlint.node.AttrNode] nodes.
+- The `processor` module provides processor related classes:
+  [Processor][xrlint.processor.Processor] comprising processor metadata
+  [ProcessorMeta][xrlint.processor.ProcessorMeta] 
+  and the processor operation [ProcessorOp][xrlint.processor.ProcessorOp].
+- The `result` module provides data classes that are used to 
+  represent validation results:
+  [Result][xrlint.result.Result] composed of [Messages][xrlint.result.Message],
+  which again may contain [Suggestions][xrlint.result.Suggestion].
+- Finally, the `testing` module provides classes for rule testing:
+  [RuleTester][xrlint.testing.RuleTester] that is made up 
+  of [RuleTest][xrlint.testing.RuleTest]s.
+
+Note: the `xrlint.all` convenience module exports all of the above from a 
+  single module.
+  
 ::: xrlint.cli.engine.XRLint
 
-## Function `new_linter()`
-
 ::: xrlint.linter.new_linter
 
-## Class `Linter`
-
 ::: xrlint.linter.Linter
 
-## Class `Config`
-
 ::: xrlint.config.Config
 
-## Class `ConfigList`
-
 ::: xrlint.config.ConfigList
 
-## Class `Plugin`
-
-::: xrlint.plugin.Plugin
-
-## Class `PluginMeta`
-
-::: xrlint.plugin.PluginMeta
+::: xrlint.rule.Rule
 
-## Class `Processor`
+::: xrlint.rule.RuleMeta
 
-::: xrlint.processor.Processor
+::: xrlint.rule.RuleOp
 
-## Class `ProcessorMeta`
+::: xrlint.rule.RuleContext
 
-::: xrlint.processor.ProcessorMeta
+::: xrlint.rule.RuleExit
 
-## Class `ProcessorOp`
+::: xrlint.node.Node
 
-::: xrlint.processor.ProcessorOp
+::: xrlint.node.XarrayNode
 
-## Class `RuleConfig`
+::: xrlint.node.DatasetNode
 
-::: xrlint.rule.RuleConfig
+::: xrlint.node.DataArrayNode
 
-## Class `Rule`
+::: xrlint.node.AttrsNode
 
-::: xrlint.rule.Rule
+::: xrlint.node.AttrNode
 
-## Class `RuleMeta`
+::: xrlint.plugin.Plugin
 
-::: xrlint.rule.RuleMeta
+::: xrlint.plugin.PluginMeta
 
-## Class `RuleOp`
+::: xrlint.processor.Processor
 
-::: xrlint.rule.RuleOp
+::: xrlint.processor.ProcessorMeta
+ 
+::: xrlint.processor.ProcessorOp
 
-## Class `RuleContext`
+::: xrlint.result.Result
 
-::: xrlint.rule.RuleContext
+::: xrlint.result.Message
 
-## Class `RuleTester`
+::: xrlint.result.Suggestion
 
 ::: xrlint.testing.RuleTester
 
-## Class `RuleTest`
-
 ::: xrlint.testing.RuleTest
 
-## Class `Result`
-
-::: xrlint.result.Result
-
-## Class `Message`
-
-::: xrlint.result.Message
-
-## Class `Suggestion`
-
-::: xrlint.result.Suggestion
-

docs/index.md

@@ -3,7 +3,7 @@
 
 XRLint is a [linting](https://en.wikipedia.org/wiki/Lint_(software)) 
 tool and library for [xarray]() datasets.
-Its design is heavily inspired by [ESLint](https://eslint.org/).
+Its design is heavily inspired by the awesome [ESLint](https://eslint.org/).
 
 
 ## Features 
@@ -18,13 +18,13 @@ Its design is heavily inspired by [ESLint](https://eslint.org/).
 
 ## Inbuilt Rules
 
-The following rule plugins are currently built into the code base:
+The following plugins provide XRLint's [inbuilt rules](rule-ref.md):
 
-- `core`: Implementing the rules for
+- `core`: implementing the rules for
   [tidy data](https://tutorial.xarray.dev/intermediate/data_cleaning/05.1_intro.html)
   and the 
   [CF-Conventions](https://cfconventions.org/cf-conventions/cf-conventions.html).
-- `xcube`: Implementing the rules for 
+- `xcube`: implementing the rules for 
   [xcube datasets](https://xcube.readthedocs.io/en/latest/cubespec.html).
   Note, this plugin is fully optional. You must manually configure 
   it to apply its rules. It may be moved into a separate GitHub repo 

environment.yml

@@ -13,6 +13,7 @@ dependencies:
   - black
   - flake8
   - mkdocs
+  - mkdocs-autorefs
   - mkdocs-material
   - mkdocstrings
   - mkdocstrings-python

mkdocs.yml

@@ -5,58 +5,59 @@ repo_name: bcdev/xrlint
 copyright: Copyright © 2025 Brockmann Consult
 
 nav:
-    - Overview: index.md
-    - Getting Started: start.md
-    - Configuration: config.md
-    - Rule Reference: rule-ref.md
-    - CLI: cli.md
-    - Python API: api.md
-    - About: about.md
+  - Overview: index.md
+  - Getting Started: start.md
+  - Configuration: config.md
+  - Rule Reference: rule-ref.md
+  - CLI: cli.md
+  - Python API: api.md
+  - About: about.md
 
 theme:
-    name: material
-    # logo: assets/logo.png
-    # favicon: assets/logo-small.png
-    palette:
-        # Palette toggle for light mode
-        - scheme: default
-          primary: blue grey
-          toggle:
-              icon: material/brightness-7
-              name: Switch to dark mode
-        # Palette toggle for dark mode
-        - scheme: slate
-          primary: blue grey
-          toggle:
-              icon: material/brightness-4
-              name: Switch to light mode
+  name: material
+  # logo: assets/logo.png
+  # favicon: assets/logo-small.png
+  palette:
+    # Palette toggle for light mode
+    - scheme: default
+      primary: blue grey
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    # Palette toggle for dark mode
+    - scheme: slate
+      primary: blue grey
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
 
 markdown_extensions:
-    - attr_list
-    - admonition
-    - pymdownx.details
-    - pymdownx.superfences
-    - pymdownx.emoji:
-        emoji_index: !!python/name:material.extensions.emoji.twemoji
-        emoji_generator: !!python/name:material.extensions.emoji.to_svg
+  - attr_list
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
 
 extra:
-    social:
-        - icon: fontawesome/brands/github
-          link: https://github.com/bcdev/xrlint
-        - icon: fontawesome/brands/python
-          link: https://pypi.org/project/xrlint/
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/bcdev/xrlint
+    - icon: fontawesome/brands/python
+      link: https://pypi.org/project/xrlint/
 
 plugins:
-    - search
-    - autorefs
-    - mkdocstrings:
-          handlers:
-              python:
-                  options:
-                      show_root_toc_entry: false
-                      show_root_heading: false
-                      show_source: true
-                      heading_level: 3
-                      annotations_path: brief
-                      members_order: source
+  - search
+  - autorefs
+  - mkdocstrings:
+      handlers:
+        python:
+          options:
+            docstring_style: google
+            show_root_toc_entry: true
+            show_root_heading: true
+            show_source: true
+            heading_level: 2
+            annotations_path: brief
+            members_order: source

notebooks/mkdataset.py

@@ -8,24 +8,18 @@
 
 def make_dataset() -> xr.Dataset:
     """Create a dataset that passes xrlint core rules."""
-    
+
     return xr.Dataset(
         attrs=dict(title="SST-Climatology Subset"),
         coords={
             "x": xr.DataArray(
-                np.linspace(-180, 180, nx),
-                dims="x", 
-                attrs={"units": "degrees"}
+                np.linspace(-180, 180, nx), dims="x", attrs={"units": "degrees"}
             ),
             "y": xr.DataArray(
-                np.linspace(-90, 90, ny),
-                dims="y", 
-                attrs={"units": "degrees"}
+                np.linspace(-90, 90, ny), dims="y", attrs={"units": "degrees"}
             ),
             "time": xr.DataArray(
-                [2010 + y for y in range(nt)], 
-                dims="time", 
-                attrs={"units": "years"}
+                [2010 + y for y in range(nt)], dims="time", attrs={"units": "years"}
             ),
             "spatial_ref": xr.DataArray(
                 0,
@@ -38,27 +32,25 @@ def make_dataset() -> xr.Dataset:
         },
         data_vars={
             "sst": xr.DataArray(
-                np.random.random((nt, ny, nx)), 
-                dims=["time", "y", "x"], 
-                attrs={"units": "kelvin", "grid_mapping": "spatial_ref"}
+                np.random.random((nt, ny, nx)),
+                dims=["time", "y", "x"],
+                attrs={"units": "kelvin", "grid_mapping": "spatial_ref"},
             ),
             "sst_anomaly": xr.DataArray(
-                np.random.random((nt, ny, nx)), 
-                dims=["time", "y", "x"], 
-                attrs={"units": "kelvin", "grid_mapping": "spatial_ref"}
-            )
+                np.random.random((nt, ny, nx)),
+                dims=["time", "y", "x"],
+                attrs={"units": "kelvin", "grid_mapping": "spatial_ref"},
+            ),
         },
     )
 
 
-def make_dataset_with_issues() -> xr.Dataset:    
+def make_dataset_with_issues() -> xr.Dataset:
     """Create a dataset that produces issues with xrlint core rules."""
     invalid_ds = make_dataset()
     invalid_ds.attrs = {}
     invalid_ds.sst.attrs["units"] = 1
     invalid_ds["sst_avg"] = xr.DataArray(
-        np.random.random((nx, ny)), 
-        dims=["x", "y"], 
-        attrs={"units": "kelvin"}
+        np.random.random((nx, ny)), dims=["x", "y"], attrs={"units": "kelvin"}
     )
     return invalid_ds

pyproject.toml

@@ -74,6 +74,7 @@ dev = [
 ]
 doc = [
   "mkdocs",
+  "mkdocs-autorefs",
   "mkdocs-material",
   "mkdocstrings",
   "mkdocstrings-python"