initial docs

Author: forman

.gitignore

@@ -9,6 +9,7 @@ __pycache__
 *.egg-info
 .coverage
 htmlcov/
+site/
 
 # Jupyter
 .ipynb_checkpoints

docs/about.md

@@ -0,0 +1,73 @@
+# About XRLint
+
+## Changelog
+
+You can find the complete XRLint changelog 
+[here](https://github.com/bcdev/xrlint/blob/main/CHANGES.md). 
+
+## Reporting
+
+If you have suggestions, ideas, feature requests, or if you have identified
+a malfunction or error, then please 
+[post an issue](https://github.com/bcdev/xrlint/issues). 
+
+## Contributions
+
+The XRLint project welcomes contributions of any form
+as long as you respect our 
+[code of conduct](https://github.com/bcdev/xrlint/blob/main/CODE_OF_CONDUCT.md)
+and follow our 
+[contribution guide](https://github.com/bcdev/xrlint/blob/main/CONTRIBUTING.md).
+
+If you'd like to submit code or documentation changes, we ask you to provide a 
+pull request (PR) 
+[here](https://github.com/bcdev/xrlint/pulls). 
+For code and configuration changes, your PR must be linked to a 
+corresponding issue. 
+
+## Development
+
+To set up development environment, with repository root as current
+working directory:
+
+```bash
+pip install .[dev,doc]
+```
+
+### Testing and Coverage
+
+XRLint uses [pytest](https://docs.pytest.org/) for unit-level testing 
+and code coverage analysis.
+
+```bash
+pytest --cov=xrlint --cov-report html
+```
+
+### Code Style
+
+XRLint source code is formatted using the [black](https://black.readthedocs.io/) tool.
+
+```bash
+black .
+```
+
+### Documentation
+
+XRLint documentation is built using the [mkdocs](https://www.mkdocs.org/) tool.
+
+With repository root as current working directory:
+
+```bash
+pip install .[doc]
+
+mkdocs build
+mkdocs serve
+mkdocs gh-deploy
+```
+
+## License
+
+XRLint is open source made available under the terms and conditions of the 
+[MIT License](https://github.com/bcdev/xrlint/blob/main/LICENSE).
+
+Copyright © 2025 Brockmann Consult Development

docs/api.md

@@ -0,0 +1,19 @@
+# Python API
+
+All described objects can be imported from the `xrlint.all` module.
+
+## Function `new_linter()`
+
+::: xrlint.linter.new_linter
+
+## Class `Linter`
+
+::: xrlint.linter.Linter
+
+## Class `Config`
+
+::: xrlint.config.Config
+
+## Class `RuleConfig`
+
+::: xrlint.rule.RuleConfig

docs/cli.md

@@ -0,0 +1,21 @@
+# Command Line Interface
+
+After installation, the `xrlint` command can be used from the terminal. 
+The following are the command's options and arguments:
+
+```
+Usage: xrlint [OPTIONS] [FILES]...
+
+  Lint the given FILES.
+
+Options:
+  --no-default-config   Disable use of default configuration from
+                        xrlint.config.*
+  -c, --config PATH     Use this configuration, overriding xrlint.config.*
+                        config options if present
+  -f, --format NAME     Use a specific output format - default: simple
+  --max-warnings COUNT  Number of warnings to trigger nonzero exit code -
+                        default: -1
+  --version             Show the version and exit.
+  --help                Show this message and exit.
+```

docs/index.md

@@ -0,0 +1 @@
+# XRLint Documentation

mkdocs.yml

@@ -0,0 +1,54 @@
+site_name: XRLint
+repo_url: https://github.com/bcdev/xrlint
+repo_name: bcdev/xrlint
+
+copyright: Copyright © 2025 Brockmann Consult
+
+nav:
+    - Overview: index.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
+
+markdown_extensions:
+    - admonition
+    - pymdownx.details
+    - pymdownx.superfences
+
+extra:
+    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: false
+                      heading_level: 3
+                      annotations_path: brief

xrlint/config.py

@@ -111,10 +111,8 @@ class Config(ToDictMixin):
 
     @property
     def global_ignores(self) -> list[str]:
-        """Get the _global ignores_ of this configuration.
-
-        Returns: A list of global ignore patterns or an empty list
-        if none are configured.
+        """The list of `ignores` patterns from this configuration which
+        are _global ignores_.
         """
         return (
             self.ignores

xrlint/rule.py

@@ -113,19 +113,48 @@ class Rule:
 
 @dataclass(frozen=True)
 class RuleConfig:
-    """Rule configuration.
+    """A rule configuration.
 
     Args:
-        severity: 0, 1, 2
-
+        severity: rule severity, one of `2` (error), `1` (warn), or `0` (off)
+        args: rule operation arguments.
+        kwargs: rule operation keyword-arguments.
     """
 
     severity: Literal[0, 1, 2]
+    """Rule severity."""
+
     args: tuple[Any, ...] = field(default_factory=tuple)
+    """Rule operation arguments."""
+
     kwargs: dict[str, Any] = field(default_factory=dict)
+    """Rule operation keyword-arguments."""
 
     @classmethod
     def from_value(cls, value: Any) -> "RuleConfig":
+        """Convert `value` into a `RuleConfig` object.
+
+        A rule configuration value can either be a rule _severity_,
+        or a list where the first element is a rule
+        _severity_ and subsequent elements are rule arguments:
+
+        - _severity_
+        - `[`_severity_`]`
+        - `[`_severity_`,` _arg-1 | kwargs_ `]`
+        - `[`_severity_`,` _arg-1_`,` _arg-2_`,` ...`,` _arg-n | kwargs_`]`
+
+        The rule _severity_ is either
+
+        - one of `"error"`, `"warn"`, `"off"` or
+        - one of `2` (error), `1` (warn), `0` (off)
+
+        Args:
+            value: A rule severity or a list where the first element is a rule
+                severity and subsequent elements are rule arguments.
+                If the value is already of type `RuleConfig`it is returned as-is.
+        Returns:
+            A `RuleConfig` object.
+        """
         if isinstance(value, RuleConfig):
             return value