Remove skimage specific array expression syntax (#77)

* Remove skimage specific array expression syntax

Which was somewhat ambiguious and more complicated than necessary.
Instead let's go with the convention used by scikit-learn.

* Remove skimage array forms from example package

* Replace "e.g." with "for example"

The latter is clearer and easier to understand language.

Author: lagru

docs/introduction.md

@@ -110,7 +110,7 @@ ski = "skimage"
 "sklearn.tree" = "sklearn.tree"
 ```
 
-which will enable any type that is prefixed with `ski.` or `sklearn.tree.`, e.g. `ski.transform.AffineTransform` or `sklearn.tree.DecisionTreeClassifier`.
+which will enable any type that is prefixed with `ski.` or `sklearn.tree.`, for example `ski.transform.AffineTransform` or `sklearn.tree.DecisionTreeClassifier`.
 
 :::{important}
 Docstub doesn't check that types actually exist or if a symbol is a valid type.
@@ -162,7 +162,7 @@ In those cases, you docstub provides a few approaches to dealing with this.
 Docstub will always preserve inline type annotations, regardless of what the docstring contains.
 This is useful for example, if you want to express something that isn't yet supported by Python's type system.
 
-E.g., consider the docstring type of `ord` parameter in [`numpy.linalg.matrix_norm`](https://numpy.org/doc/stable/reference/generated/numpy.linalg.matrix_norm.html)
+For example, consider the docstring type of `ord` parameter in [`numpy.linalg.matrix_norm`](https://numpy.org/doc/stable/reference/generated/numpy.linalg.matrix_norm.html)
 ```rst
 ord : {1, -1, 2, -2, inf, -inf, ‘fro’, ‘nuc’}, optional
 ```
@@ -181,7 +181,7 @@ At its heart, docstub transforms Python source files into stub files.
 You can tell docstub to temporarily stop that transformation for a specific area with a comment directive.
 Wrapping lines of code with `docstub: off` and `docstub: on` comments will preserve these lines completely.
 
-E.g., consider the following example:
+For example, consider the following example:
 ```python
 class Foo:
     # docstub: off

docs/typing_syntax.md

@@ -45,7 +45,7 @@ This extends the basic subscription syntax for [generics](https://typing.python.
 | `CONTAINER of (X or Y)` | `CONTAINER[X \| Y]`    |
 
 For the simple case `CONTAINER of X`, where `X` is a name, you can append `(s)` to indicate the plural form.
-E.g., `list of float(s)`.
+For example, `list of float(s)`.
 
 Variants of for [**tuples**](https://typing.python.org/en/latest/spec/tuples.html)
 
@@ -73,28 +73,30 @@ In the future, docstub may warn against or disallow nesting these natural langua
 
 This expression allows adding shape and datatype information for data structures like [NumPy arrays](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html).
 
-`array` and `ndarray`, and `array-like` and `array_like` can be used interchange-ably.
+`array` and `ndarray`, and `array-like` and `array_like` can be used interchange-ably for the variable `ARRAY` below.
+
+| Docstring type                         | Python type annotation |
+|----------------------------------------|------------------------|
+| `ARRAY of dtype DTYPE`                 | `ARRAY[DTYPE]`         |
+| `ARRAY of dtype DTYPE and shape SHAPE` | `ARRAY[DTYPE]`         |
+| `ARRAY of shape SHAPE`                 | `ARRAY[DTYPE]`         |
+| `ARRAY of shape SHAPE and dtype DTYPE` | `ARRAY[DTYPE]`         |
+
+For example
+
+| Docstring type                           | Python type annotation |
+|------------------------------------------|------------------------|
+| `array of dtype int`                     | `ndarray[int]`         |
+| `ndarray of dtype bool and shape (4, 4)` | `ndarray[bool]`        |
+| `array-like of dtype float`              | `ArrayLike[float]`     |
+| `array_like of shape (M, 2)`             | `ArrayLike`            |
 
-| Docstring type              | Python type annotation |
-|-----------------------------|------------------------|
-| `array of DTYPE`            | `ndarray[DTYPE]`       |
-| `ndarray of dtype DTYPE`    | `ndarray[DTYPE]`       |
-| `array-like of DTYPE`       | `ArrayLike[DTYPE]`     |
-| `array_like of dtype DTYPE` | `ArrayLike[DTYPE]`     |
 
 :::{note}
 Noting the **shape** of an array in the docstring is supported.
-However, Python's typing system is not yet able to express this information.
-It is therefore not included in the resulting type annotation.
+However, [support for including shapes in generated stubs](https://github.com/scientific-python/docstub/issues/76) is not yet included in docstub.
 :::
 
-| Docstring type           | Python type annotation |
-|--------------------------|------------------------|
-| `(3,) array of DTYPE`    | `ndarray[DTYPE]`       |
-| `(X, Y) array of DTYPE`  | `ndarray[DTYPE]`       |
-| `([P,] M, N) array-like` | `ArrayLike`            |
-| `(M, ...) ndarray`       | `ArrayLike`            |
-
 
 ## Literals
 
@@ -113,7 +115,7 @@ However, `Literal[X]` is more explicit.
 
 :::{warning}
 Python's `typing.Literal` only supports a restricted set of parameters.
-E.g., `float` literals are not yet supported by the type system but are allowed by docstub.
+For example, `float` literals are not yet supported by the type system but are allowed by docstub.
 Addressing this use case is on the roadmap.
 See [issue 47](https://github.com/scientific-python/docstub/issues/47) for more details.
 :::

examples/example_pkg/_numpy.py

@@ -20,12 +20,12 @@ def func_ndarray(a1, a2, a3, a4=None):
     ----------
     a1 : ndarray
     a2 : np.NDArray
-    a3 : (N, 3) ndarray of float
+    a3 : ndarray of dtype float and shape (N, 3)
     a4 : ndarray of shape (1,) and dtype uint8
 
     Returns
     -------
-    r1 : uint8 array
+    r1 : array of dtype uint8
     r2 : array of dtype complex and shape (1, ..., 3)
     """
 
@@ -37,11 +37,11 @@ def func_array_like(a1, a2, a3, a4):
     ----------
     a1 : array-like
     a2 : array_like
-    a3 : (N, 3) array-like of float
+    a3 : array-like of dtype float and shape (N, 3)
     a4 : array-like of shape (1,) and dtype uint8
 
     Returns
     -------
-    r1 : uint8 array-like
+    r1 : array-like of dtype uint8
     r2 : array_like of dtype complex and shape (1, ..., 3)
     """

src/docstub/doctype.lark

@@ -89,10 +89,6 @@ _natlang_mapping: qualname "of" "{" type ":" type "}"
 // A natural language alternative to describe arrays with a dtype and shape.
 natlang_array: array_name "of dtype" dtype ("and shape" shape)?
     | array_name "of shape" shape ("and dtype" dtype)?
-    | shape array_name ("of" dtype)?
-    | shape? array_name "of" dtype
-    | shape dtype array_name
-    | dtype array_name
 
 
 // Currently a bit of a hack. Since the `array_expression` is ambiguous, we

tests/test_docstrings.py

@@ -228,12 +228,9 @@ def test_rst_role(self, doctype, expected):
     @pytest.mark.parametrize(
         ("fmt", "expected_fmt"),
         [
-            ("{shape} {name}",                            "{name}"),
-            ("{shape} {name} of {dtype}",                 "{name}[{dtype}]"),
-            ("{shape} {dtype} {name}",                    "{name}[{dtype}]"),
-            ("{dtype} {name}",                            "{name}[{dtype}]"),
             ("{name} of shape {shape} and dtype {dtype}", "{name}[{dtype}]"),
             ("{name} of dtype {dtype} and shape {shape}", "{name}[{dtype}]"),
+            ("{name} of {dtype}", "{name}[{dtype}]"),
         ],
     )
     @pytest.mark.parametrize("name", ["array", "ndarray", "array-like", "array_like"])
@@ -261,7 +258,6 @@ def escape(name: str) -> str:
         ("doctype", "expected"),
         [
             ("ndarray of dtype (int or float)", "ndarray[int | float]"),
-            ("([P,] M, N) (int or float) array", "array[int | float]"),
         ],
     )
     def test_natlang_array_specific(self, doctype, expected):