Fix cross-references to helper functions and some RST issues

Author: asmeurer

array_api_compat/common/_helpers.py

@@ -452,7 +452,7 @@ def to_device(x: Array, device: Device, /, *, stream: Optional[Union[int, Any]]
     <https://docs.cupy.dev/en/stable/reference/generated/cupy.cuda.Device.html>`_
     and `Stream
     <https://docs.cupy.dev/en/stable/reference/generated/cupy.cuda.Stream.html>`_
-    objects. For PyTorch, this is the same as ``x.to(device)
+    objects. For PyTorch, this is the same as `x.to(device)
     <https://pytorch.org/docs/stable/generated/torch.Tensor.to.html>`_ (the
     ``stream`` argument is not supported in PyTorch).
 

docs/conf.py

@@ -37,6 +37,12 @@
 
 # Make sphinx give errors for bad cross-references
 nitpicky = True
+# autodoc wants to make cross-references for every type hint. But a lot of
+# them don't actually refer to anything that we have a document for.
+nitpick_ignore = [
+    ("py:class", "Array"),
+    ("py:class", "Device"),
+]
 
 # Lets us use single backticks for code in RST
 default_role = 'code'

docs/dev/implementation-notes.md

@@ -14,9 +14,9 @@ should be taken into account:
 
 - *No Hard Dependencies.* Although array-api-compat "depends" on NumPy, CuPy,
   PyTorch, etc., it does not hard depend on them. These libraries are not
-  imported unless either an array object is passed to `array_namespace()`, or
-  the specific `array_api_compat.<namespace>` sub-namespace is explicitly
-  imported.
+  imported unless either an array object is passed to
+  {func}`~.array_namespace()`, or the specific `array_api_compat.<namespace>`
+  sub-namespace is explicitly imported.
 
 - *Vendorability.* array-api-compat should be [vendorable](vendoring). This
   means that, for instance, all imports in the library are relative imports.
@@ -35,7 +35,7 @@ should be taken into account:
 
   This also means that we do not at this point in time implement anything
   other than wrappers for functions in the standard, and basic [helper
-  functions](../helper-functions.md) that would be useful for most users of
+  functions](../helper-functions.rst) that would be useful for most users of
   array-api-compat. The addition of functions that are not part of the array
   API standard is currently out-of-scope for this package.
 
@@ -59,7 +59,7 @@ should be taken into account:
   functions](https://data-apis.org/array-api/latest/API_specification/elementwise_functions.html)
   instead of
   [operators](https://data-apis.org/array-api/latest/API_specification/array_object.html#operators),
-  and by using the [helper functions](../helper-functions.md) provided by
+  and by using the [helper functions](../helper-functions.rst) provided by
   array-api-compat instead of attributes or methods like `x.to_device()`.
 
 - *Avoid Restricting Behavior that is Outside the Scope of the Standard.* All
@@ -145,7 +145,7 @@ The majority of the behavior for array-api-compat is tested by the
 the array API standard. There are also array-api-compat specific tests in
 [`tests/`](https://github.com/data-apis/array-api-compat/tree/main/tests).
 These tests should be limited to things that are not tested by the test suite,
-e.g., tests for [helper functions](../helper-functions.md) or for behavior
+e.g., tests for [helper functions](../helper-functions.rst) or for behavior
 that is not strictly required by the standard.
 
 array-api-tests is run against all supported libraries are tested on CI

docs/helper-functions.rst

@@ -13,15 +13,16 @@ array_namespace
 The `array_namespace()` function is the primary entry-point for array API
 consuming libraries.
 
+
 .. autofunction:: array_namespace
-   :canonical: array_api_compat.array_namespace
+.. autofunction:: is_array_api_obj
 
 Array Method Helpers
 --------------------
 
 array-api-compat does not attempt to wrap or monkey patch the array object for
 any library. Consequently, any API differences for the [array
-object](https://data-apis.org/array-api/latest/API_specification/array_object.htmlK
+object](https://data-apis.org/array-api/latest/API_specification/array_object.html)
 cannot be directly wrapped. Some libraries do not define some of these methods
 or define them differently. For these, helper functions are provided which can
 be used instead.
@@ -35,14 +36,13 @@ instead, which would be wrapped.
 .. autofunction:: to_device
 .. autofunction:: size
 
-Inspect Helpers
----------------
+Inspection Helpers
+------------------
 
 These convenience functions can be used to test if an array comes from a
 specific library without importing that library if it hasn't been imported
 yet.
 
-.. autofunction:: is_array_api_obj
 .. autofunction:: is_numpy_array
 .. autofunction:: is_cupy_array
 .. autofunction:: is_torch_array

docs/index.md

@@ -23,7 +23,7 @@ version](https://data-apis.org/array-api/2022.12/) of the standard.
 python -m pip install array-api-compat
 ```
 
-and [Conda-forge](https://anaconda.org/conda-forge/array-api-compat)
+and [conda-forge](https://anaconda.org/conda-forge/array-api-compat)
 
 ```
 conda install --channel conda-forge array-api-compat
@@ -32,7 +32,7 @@ conda install --channel conda-forge array-api-compat
 ## Usage
 
 The typical usage of this library will be to get the corresponding array API
-compliant namespace from the input arrays using {func}`array_namespace()`, like
+compliant namespace from the input arrays using {func}`~.array_namespace()`, like
 
 ```py
 def your_function(x, y):

docs/supported-array-libraries.md

@@ -4,8 +4,8 @@ The following array libraries are supported. This page outlines the known
 differences between this library and the array API specification for the
 supported packages.
 
-Note that the [`array_namespace()`](helper-functions.md) helper will also
-support any array library that explicitly supports the array API by defining
+Note that the {func}`~.array_namespace()` helper will also support any array
+library that explicitly supports the array API by defining
 [`__array_namespace__`](https://data-apis.org/array-api/latest/API_specification/generated/array_api.array.__array_namespace__.html).
 
 Any reasonably popular array library is in-scope for array-api-compat,
@@ -17,18 +17,18 @@ complexity. If your favorite library is not supported, feel free to open an
 
 NumPy 2.0 has full array API compatibility. This package is not strictly
 necessary for NumPy 2.0 support, but may still be useful for the support of
-other libraries, as well as for the [helper functions](helper-functions.md).
+other libraries, as well as for the [helper functions](helper-functions.rst).
 
 For NumPy 1.26, as well as corresponding versions of CuPy, the following
 deviations from the standard should be noted:
 
 - The array methods `__array_namespace__`, `device` (for NumPy), `to_device`,
   and `mT` are not defined. This reuses `np.ndarray` and `cp.ndarray` and we
   don't want to monkey patch or wrap it. The [helper
-  functions](helper-functions.md) `device()` and `to_device()` are provided to
-  work around these missing methods. `x.mT` can be replaced with
-  `xp.linalg.matrix_transpose(x)`. `array_namespace(x)` should be used instead
-  of `x.__array_namespace__`.
+  functions](helper-functions.rst) {func}`~.device()` and {func}`~.to_device()`
+  are provided to work around these missing methods. `x.mT` can be replaced
+  with `xp.linalg.matrix_transpose(x)`. {func}`~.array_namespace()` should be
+  used instead of `x.__array_namespace__`.
 
 - Value-based casting for scalars will be in effect unless explicitly disabled
   with the environment variable `NPY_PROMOTION_STATE=weak` or
@@ -63,14 +63,14 @@ version.
 
 - Like NumPy/CuPy, we do not wrap the `torch.Tensor` object. It is missing the
   `__array_namespace__` and `to_device` methods, so the corresponding helper
-  functions `array_namespace()` and `to_device()` in this library should be
-  used instead (see above).
+  functions {func}`~.array_namespace()` and {func}`~.to_device()` in this
+  library should be used instead.
 
 - The `x.size` attribute on `torch.Tensor` is a function that behaves
   differently from
   [`x.size`](https://data-apis.org/array-api/draft/API_specification/generated/array_api.array.size.html)
-  in the spec. Use the `size(x)` helper function as a portable workaround (see
-  above).
+  in the spec. Use the {func}`~.size()` helper function as a portable
+  workaround.
 
 - PyTorch does not have unsigned integer types other than `uint8`, and no
   attempt is made to implement them here.
@@ -95,8 +95,7 @@ version.
   [`var()`](https://data-apis.org/array-api/latest/API_specification/generated/array_api.var.html#array_api.var)
   do not support floating-point `correction`.
 
-- The `stream` argument of the `to_device()` helper (see above) is not
-  supported.
+- The `stream` argument of the {func}`~.to_device()` helper is not supported.
 
 - As with NumPy, type annotations and positional-only arguments may not
   exactly match the spec for functions that are not wrapped at all.