Skip to content

Commit fa7ff57

Browse files
formanforman
committed
docs update
1 parent 54515c0 commit fa7ff57

File tree

3 files changed

+114
-66
lines changed

3 files changed

+114
-66
lines changed

‎README.md‎

Lines changed: 18 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -8,78 +8,31 @@
88

99
XRLint is a [linter](https://en.wikipedia.org/wiki/Lint_(software))
1010
tool and library for [xarray]() datasets.
11-
1211
Its design is heavily inspired by [ESLint](https://eslint.org/).
1312

13+
**IMPORTANT NOTE**: This project just started and is under development,
14+
there is no stable release yet.
15+
16+
## Features
17+
18+
- Flexible validation for `xarray.Dataset` objects by configurable _rules_.
19+
- Available from _CLI_ and _Python API_.
20+
- _Custom plugins_ providing _custom rule_ sets allow addressing
21+
different dataset conventions.
22+
- _Project-specific configurations_ including configuration of individual
23+
rules and file-specific settings.
24+
1425
## Inbuilt Rules
1526

27+
The following rule plugins are currently built into the code base:
28+
1629
- `core`: Implementing the rules for
1730
[tiny data](https://tutorial.xarray.dev/intermediate/data_cleaning/05.1_intro.html)
1831
and the
19-
[CF-Conventions](https://cfconventions.org/cf-conventions/cf-conventions.html)
32+
[CF-Conventions](https://cfconventions.org/cf-conventions/cf-conventions.html).
2033

2134
- `xcube`: Implementing the rules for
22-
[xcube datasets](https://xcube.readthedocs.io/en/latest/cubespec.html)
23-
24-
## To-Dos
25-
26-
### Required
27-
28-
- populate `core` plugin by more rules
29-
- populate `xcube` plugin by more rules
30-
- add `docs`
31-
- configure api docs, use mkdocstrings ref syntax in docstrings
32-
- generate markdown rule reference for the docs
33-
- CI for package publishing
34-
35-
### Desired
36-
37-
- add some more tests so we reach 99% coverage
38-
- introduce `dataset_options` config:
39-
- `opener: OpenerOp`
40-
- `opener_options: dict[str, Any]`
41-
- implement `autofix` feature
42-
43-
### Nice to have
44-
45-
- use `RuleMeta.type`, it is currently unused
46-
- use `RuleTest.expected`, it is currently unused
47-
- use `processor: ProcessorOp` config, it is currently unused
48-
- add missing community standards,
49-
see https://github.com/bcdev/xrlint/community
50-
51-
## Ideas
52-
53-
### Other plugins
54-
55-
- `sgrid`: https://sgrid.github.io/sgrid/
56-
- `ugrid`: https://ugrid-conventions.github.io/ugrid-conventions/
57-
58-
## Generalize data linting
59-
60-
Do not limit verification to `xr.Dataset`.
61-
However, this requires new rule sets.
62-
63-
To allow for other data models, we need to allow
64-
for a specific verifier type for a given data type.
65-
66-
The verifier verifies specific node types
67-
that are characteristic for a data type.
68-
69-
To do so a traverser must traverse the elements of the data
70-
and pass each node to the verifier.
71-
72-
Note, this is the [_Visitor Pattern_](https://en.wikipedia.org/wiki/Visitor_pattern),
73-
where the verifier is the _Visitor_ and a node refers to _Element_.
74-
75-
To support the CLI mode, we need different data opener
76-
types that can read the data from a file path.
35+
[xcube datasets](https://xcube.readthedocs.io/en/latest/cubespec.html).
36+
Note this plugins will be moved into a separate GitHub repo later
37+
once XRLint is mature enough.
7738

78-
1. open data, if given data is a file path:
79-
- find opener for file path
80-
- open data
81-
2. verify data
82-
- find root element type and visitor type for data
83-
- call the root element `accept(verifier)` that verifies the
84-
root element `verify.root()` and starts traversal of
85-
child elements.

‎docs/index.md‎

Lines changed: 33 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,33 @@
1-
# XRLint Documentation
1+
# XRLint - A linter for xarray datasets
2+
3+
4+
XRLint is a [linter](https://en.wikipedia.org/wiki/Lint_(software))
5+
tool and library for [xarray]() datasets.
6+
Its design is heavily inspired by [ESLint](https://eslint.org/).
7+
8+
**IMPORTANT NOTE**: This project just started and is under development,
9+
there is no stable release yet.
10+
11+
## Features
12+
13+
- Flexible validation for `xarray.Dataset` objects by configurable _rules_.
14+
- Available from _CLI_ and _Python API_.
15+
- _Custom plugins_ providing _custom rule_ sets allow addressing
16+
different dataset conventions.
17+
- _Project-specific configurations_ including configuration of individual
18+
rules and file-specific settings.
19+
20+
## Inbuilt Rules
21+
22+
The following rule plugins are currently built into the code base:
23+
24+
- `core`: Implementing the rules for
25+
[tiny data](https://tutorial.xarray.dev/intermediate/data_cleaning/05.1_intro.html)
26+
and the
27+
[CF-Conventions](https://cfconventions.org/cf-conventions/cf-conventions.html).
28+
29+
- `xcube`: Implementing the rules for
30+
[xcube datasets](https://xcube.readthedocs.io/en/latest/cubespec.html).
31+
Note this plugins will be moved into a separate GitHub repo later
32+
once XRLint is mature enough.
33+

‎docs/todo.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# To Do
2+
3+
## Required
4+
5+
- populate `core` plugin by more rules
6+
- populate `xcube` plugin by more rules
7+
- add `docs`
8+
- configure api docs, use mkdocstrings ref syntax in docstrings
9+
- generate markdown rule reference for the docs
10+
- CI for package publishing
11+
12+
## Desired
13+
14+
- add some more tests so we reach 99% coverage
15+
- introduce `dataset_options` config:
16+
- `opener: OpenerOp`
17+
- `opener_options: dict[str, Any]`
18+
- implement `autofix` feature
19+
20+
## Nice to have
21+
22+
- use `RuleMeta.type`, it is currently unused
23+
- use `RuleTest.expected`, it is currently unused
24+
- use `processor: ProcessorOp` config, it is currently unused
25+
- add missing community standards,
26+
see https://github.com/bcdev/xrlint/community
27+
28+
# Ideas
29+
30+
## Other plugins
31+
32+
- `sgrid`: https://sgrid.github.io/sgrid/
33+
- `ugrid`: https://ugrid-conventions.github.io/ugrid-conventions/
34+
35+
## Generalize data linting
36+
37+
Do not limit verification to `xr.Dataset`.
38+
However, this requires new rule sets.
39+
40+
To allow for other data models, we need to allow
41+
for a specific verifier type for a given data type.
42+
43+
The verifier verifies specific node types
44+
that are characteristic for a data type.
45+
46+
To do so a traverser must traverse the elements of the data
47+
and pass each node to the verifier.
48+
49+
Note, this is the [_Visitor Pattern_](https://en.wikipedia.org/wiki/Visitor_pattern),
50+
where the verifier is the _Visitor_ and a node refers to _Element_.
51+
52+
To support the CLI mode, we need different data opener
53+
types that can read the data from a file path.
54+
55+
1. open data, if given data is a file path:
56+
- find opener for file path
57+
- open data
58+
2. verify data
59+
- find root element type and visitor type for data
60+
- call the root element `accept(verifier)` that verifies the
61+
root element `verify.root()` and starts traversal of
62+
child elements.
63+

0 commit comments

Comments
 (0)