Docs update

Author: forman

README.md

@@ -12,7 +12,8 @@ tool and library for [xarray]() datasets.
 Its design is heavily inspired by [ESLint](https://eslint.org/).
 
 **IMPORTANT NOTE**: This project just started and is under development, 
-there is no stable release yet.
+there is no stable release yet. See 
+[to-do list](docs/todo.md).
 
 ## Features 
 
@@ -31,7 +32,6 @@ The following rule plugins are currently built into the code base:
   [tiny 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 datasets](https://xcube.readthedocs.io/en/latest/cubespec.html).
   Note this plugins will be moved into a separate GitHub repo later 

docs/api.md

@@ -17,3 +17,19 @@ All described objects can be imported from the `xrlint.all` module.
 ## Class `RuleConfig`
 
 ::: xrlint.rule.RuleConfig
+
+## Class `Rule`
+
+::: xrlint.rule.Rule
+
+## Class `RuleMeta`
+
+::: xrlint.rule.RuleMeta
+
+## Class `RuleOp`
+
+::: xrlint.rule.RuleOp
+
+## Class `RuleContext`
+
+::: xrlint.rule.RuleContext

docs/index.md

@@ -6,7 +6,7 @@ tool and library for [xarray]() datasets.
 Its design is heavily inspired by [ESLint](https://eslint.org/).
 
 **IMPORTANT NOTE**: This project just started and is under development, 
-there is no stable release yet.
+there is no stable release yet. See [to-do list](https://github.com/bcdev/xrlint/blob/main/docs/todo.md).
 
 ## Features 
 
@@ -25,7 +25,6 @@ The following rule plugins are currently built into the code base:
   [tiny 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 datasets](https://xcube.readthedocs.io/en/latest/cubespec.html).
   Note this plugins will be moved into a separate GitHub repo later 

xrlint/config.py

@@ -55,6 +55,9 @@ class Config(ToDictMixin):
     """Configuration object.
     A configuration object contains all the information XRLint
     needs to execute on a set of dataset files.
+
+    You should not use the class constructor directly.
+    Instead, use the `Config.from_value()` function.
     """
 
     name: str | None = None
@@ -79,33 +82,33 @@ class Config(ToDictMixin):
     """
 
     linter_options: dict[str, Any] | None = None
-    """An object containing options related to the linting process."""
+    """A dictionary containing options related to the linting process."""
 
     opener_options: dict[str, Any] | None = None
-    """An object containing options that are passed to 
+    """A dictionary containing options that are passed to 
     the dataset opener.
     """
 
     processor: Union["ProcessorOp", str, None] = None
-    """processor - Either an object compatible with the `ProcessorOp` 
+    """Either an object compatible with the `ProcessorOp` 
     interface or a string indicating the name of a processor inside 
     of a plugin (i.e., `"pluginName/processorName"`).
     """
 
     plugins: dict[str, "Plugin"] | None = None
-    """An object containing a name-value mapping of plugin names to 
+    """A dictionary containing a name-value mapping of plugin names to 
     plugin objects. When `files` is specified, these plugins are only 
     available to the matching files.
     """
 
     rules: dict[str, "RuleConfig"] | None = None
-    """An object containing the configured rules. 
+    """A dictionary containing the configured rules. 
     When `files` or `ignores` are specified, these rule configurations 
     are only available to the matching files.
     """
 
     settings: dict[str, Any] | None = None
-    """An object containing name-value pairs of information 
+    """A dictionary containing name-value pairs of information 
     that should be available to all rules.
     """
 
@@ -117,8 +120,8 @@ def from_value(cls, value: Any) -> "Config":
 
         Args:
             value: A `Config` object, a `dict` containing the
-            configuration properties, or `None` which
-            converts into an empty configuration.
+                configuration properties, or `None` which
+                converts into an empty configuration.
         Returns:
             A `Config` object.
         """
@@ -161,16 +164,27 @@ def global_ignores(self) -> list[str]:
             if self.ignores
             and not (
                 self.files
-                or self.rules
-                or self.plugins
-                or self.settings
                 or self.linter_options
                 or self.opener_options
+                or self.plugins
+                or self.rules
+                or self.settings
             )
             else []
         )
 
     def get_rule(self, rule_id: str) -> "Rule":
+        """Get the rule for the given rule identifier `rule_id`.
+
+        Args:
+            rule_id: The rule identifier including plugin namespace, if any.
+                Format `<rule-name>` (builtin rules) or `<plugin-name>/<rule-name>`.
+        Returns:
+            A `Rule` object.
+        Raises:
+            ValueError: If either the plugin is unknown in this configuration
+                or the rule name is unknown.
+        """
         if "/" in rule_id:
             plugin_name, rule_name = rule_id.split("/", maxsplit=1)
         else:
@@ -333,7 +347,11 @@ def merge_configs(
 
 @dataclass(frozen=True)
 class ConfigList:
-    """A holder for a list of `Config` objects."""
+    """A holder for a list of `Config` objects.
+
+    You should not use the class constructor directly.
+    Instead, use the `ConfigList.from_value()` function.
+    """
 
     configs: list[Config] = field(default_factory=list)
     """The list of `Config` objects."""

xrlint/linter.py

@@ -19,7 +19,9 @@
 
 
 def new_linter(
-    recommended: bool = True, config: Config | dict | None = None, **config_kwargs
+    recommended: bool = True,
+    config: Config | dict | None = None,
+    **config_kwargs: dict[str, Any],
 ) -> "Linter":
     """Create a new `Linter` with all built-in plugins configured.
 
@@ -43,6 +45,9 @@ def new_linter(
 class Linter:
     """The linter.
 
+    You should not use the constructor directly.
+    Instead, use the `new_linter()` function.
+
     Args:
         config: The linter's configuration.
         config_kwargs: Individual linter configuration options.
@@ -55,7 +60,7 @@ class Linter:
     def __init__(
         self,
         config: Config | dict[str, Any] | None = None,
-        **config_kwargs,
+        **config_kwargs: dict[str, Any],
     ):
         self._config = merge_configs(config, config_kwargs)
 
@@ -70,7 +75,7 @@ def verify_dataset(
         *,
         file_path: str | None = None,
         config: Config | dict[str, Any] | None = None,
-        **config_kwargs,
+        **config_kwargs: dict[str, Any],
     ) -> Result:
         """Verify a dataset.
 

xrlint/rule.py

@@ -12,7 +12,12 @@
 
 
 class RuleContext(ABC):
-    """The context passed to the verifier of a rule."""
+    """The context passed to the verifier of a rule.
+
+    You should never create instances of this class yourself.
+    Instances of this interface are passed to the `RuleOp`'s
+    methods.
+    """
 
     @property
     @abstractmethod
@@ -65,6 +70,8 @@ def attr(self, ctx: RuleContext, node: AttrNode):
 
 @dataclass(frozen=True, kw_only=True)
 class RuleMeta(ToDictMixin):
+    """Rule metadata."""
+
     name: str
     """Rule name. Mandatory."""
 
@@ -115,6 +122,9 @@ class Rule:
 class RuleConfig:
     """A rule configuration.
 
+    You should not use the class constructor directly.
+    Instead, use the `RuleConfig.from_value()` function.
+
     Args:
         severity: rule severity, one of `2` (error), `1` (warn), or `0` (off)
         args: rule operation arguments.