10000 Make the Sphinx build error on warnings and fix all warnings (#390) · data-apis/array-api@6721451 · GitHub
[go: up one dir, main page]
Skip to content

Commit 6721451

Browse files
asmeurerasmeurer
authored
Make the Sphinx build error on warnings and fix all warnings (#390)
* Enable nitpicky mode in the Sphinx build This will make Sphinx warn when there are cross-references that it cannot find Without it, it just silently makes the text not link to anything. * Make warnings errors in the Sphinx build There are several warnings that need to be fixed, but they are all legitimate errors in the markup that should be fixed. * Remove duplicated text * Fix all Sphinx errors from nitpicky mode A lot of errors come from autodoc wanting to make cross references for every return type hint. This is disabled manually using the nitpick_ignore variable in conf.py for each instance.
1 parent ee3f3b0 commit 6721451

File tree

4 files changed

+60
-28
lines changed

4 files changed

+60
-28
lines changed

‎spec/API_specification/array_object.rst

Lines changed: 22 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -37,47 +37,47 @@ Arithmetic Operators
3737

3838
A conforming implementation of the array API standard must provide and support an array object supporting the following Python arithmetic operators.
3939

40-
- ``+x``: :meth:`array.__pos__`
40+
- ``+x``: :meth:`.array.__pos__`
4141

4242
- `operator.pos(x) <https://docs.python.org/3/library/operator.html#operator.pos>`_
4343
- `operator.__pos__(x) <https://docs.python.org/3/library/operator.html#operator.__pos__>`_
4444

45-
- `-x`: :meth:`array.__neg__`
45+
- `-x`: :meth:`.array.__neg__`
4646

4747
- `operator.neg(x) <https://docs.python.org/3/library/operator.html#operator.neg>`_
4848
- `operator.__neg__(x) <https://docs.python.org/3/library/operator.html#operator.__neg__>`_
4949

50-
- `x1 + x2`: :meth:`array.__add__`
50+
- `x1 + x2`: :meth:`.array.__add__`
5151

5252
- `operator.add(x1, x2) <https://docs.python.org/3/library/operator.html#operator.add>`_
5353
- `operator.__add__(x1, x2) <https://docs.python.org/3/library/operator.html#operator.__add__>`_
5454

55-
- `x1 - x2`: :meth:`array.__sub__`
55+
- `x1 - x2`: :meth:`.array.__sub__`
5656

5757
- `operator.sub(x1, x2) <https://docs.python.org/3/library/operator.html#operator.sub>`_
5858
- `operator.__sub__(x1, x2) <https://docs.python.org/3/library/operator.html#operator.__sub__>`_
5959

60-
- `x1 * x2`: :meth:`array.__mul__`
60+
- `x1 * x2`: :meth:`.array.__mul__`
6161

6262
- `operator.mul(x1, x2) <https://docs.python.org/3/library/operator.html#operator.mul>`_
6363
- `operator.__mul__(x1, x2) <https://docs.python.org/3/library/operator.html#operator.__mul__>`_
6464

65-
- `x1 / x2`: :meth:`array.__truediv__`
65+
- `x1 / x2`: :meth:`.array.__truediv__`
6666

6767
- `operator.truediv(x1,x2) <https://docs.python.org/3/library/operator.html#operator.truediv>`_
6868
- `operator.__truediv__(x1, x2) <https://docs.python.org/3/library/operator.html#operator.__truediv__>`_
6969

70-
- `x1 // x2`: :meth:`array.__floordiv__`
70+
- `x1 // x2`: :meth:`.array.__floordiv__`
7171

7272
- `operator.floordiv(x1, x2) <https://docs.python.org/3/library/operator.html#operator.floordiv>`_
7373
- `operator.__floordiv__(x1, x2) <https://docs.python.org/3/library/operator.html#operator.__floordiv__>`_
7474

75-
- `x1 % x2`: :meth:`array.__mod__`
75+
- `x1 % x2`: :meth:`.array.__mod__`
7676

7777
- `operator.mod(x1, x2) <https://docs.python.org/3/library/operator.html#operator.mod>`_
7878
- `operator.__mod__(x1, x2) <https://docs.python.org/3/library/operator.html#operator.__mod__>`_
7979

80-
- `x1 ** x2`: :meth:`array.__pow__`
80+
- `x1 ** x2`: :meth:`.array.__pow__`
8181

8282
- `operator.pow(x1, x2) <https://docs.python.org/3/library/operator.html#operator.pow>`_
8383
- `operator.__pow__(x1, x2) <https://docs.python.org/3/library/operator.html#operator.__pow__>`_
@@ -89,7 +89,7 @@ Array Operators
8989

9090
A conforming implementation of the array API standard must provide and support an array object supporting the following Python array operators.
9191

92-
- `x1 @ x2`: :meth:`array.__matmul__`
92+
- `x1 @ x2`: :meth:`.array.__matmul__`
9393

9494
- `operator.matmul(x1, x2) <https://docs.python.org/3/library/operator.html#operator.matmul>`_
9595
- `operator.__matmul__(x1, x2) <https://docs.python.org/3/library/operator.html#operator.__matmul__>`_
@@ -101,34 +101,34 @@ Bitwise Operators
101101

102102
A conforming implementation of the array API standard must provide and support an array object supporting the following Python bitwise operators.
103103

104-
- `~x`: :meth:`array.__invert__`
104+
- `~x`: :meth:`.array.__invert__`
105105

106106
- `operator.inv(x) <https://docs.python.org/3/library/operator.html#operator.inv>`_
107107
- `operator.invert(x) <https://docs.python.org/3/library/operator.html#operator.invert>`_
108108
- `operator.__inv__(x) <https://docs.python.org/3/library/operator.html#operator.__inv__>`_
109109
- `operator.__invert__(x) <https://docs.python.org/3/library/operator.html#operator.__invert__>`_
110110

111-
- `x1 & x2`: :meth:`array.__and__`
111+
- `x1 & x2`: :meth:`.array.__and__`
112112

113113
- `operator.and(x1, x2) <https://docs.python.org/3/library/operator.html#operator.and>`_
114114
- `operator.__and__(x1, x2) <https://docs.python.org/3/library/operator.html#operator.__and__>`_
115115

116-
- `x1 | x2`: :meth:`array.__or__`
116+
- `x1 | x2`: :meth:`.array.__or__`
117117

118118
- `operator.or(x1, x2) <https://docs.python.org/3/library/operator.html#operator.or>`_
119119
- `operator.__or__(x1, x2) <https://docs.python.org/3/library/operator.html#operator.__or__>`_
120120

121-
- `x1 ^ x2`: :meth:`array.__xor__`
121+
- `x1 ^ x2`: :meth:`.array.__xor__`
122122

123123
- `operator.xor(x1, x2) <https://docs.python.org/3/library/operator.html#operator.xor>`_
124124
- `operator.__xor__(x1, x2) <https://docs.python.org/3/library/operator.html#operator.__xor__>`_
125125

126-
- `x1 << x2`: :meth:`array.__lshift__`
126+
- `x1 << x2`: :meth:`.array.__lshift__`
127127

128128
- `operator.lshift(x1, x2) <https://docs.python.org/3/library/operator.html#operator.lshift>`_
129129
- `operator.__lshift__(x1, x2) <https://docs.python.org/3/library/operator.html#operator.__lshift__>`_
130130

131-
- `x1 >> x2`: :meth:`array.__rshift__`
131+
- `x1 >> x2`: :meth:`.array.__rshift__`
132132

133133
- `operator.rshift(x1, x2) <https://docs.python.org/3/library/operator.html#operator.rshift>`_
134134
- `operator.__rshift__(x1, x2) <https://docs.python.org/3/library/operator.html#operator.__rshift__>`_
@@ -140,32 +140,32 @@ Comparison Operators
140140

141141
A conforming implementation of the array API standard must provide and support an array object supporting the following Python comparison operators.
142142

143-
- `x1 < x2`: :meth:`array.__lt__`
143+
- `x1 < x2`: :meth:`.array.__lt__`
144144

145145
- `operator.lt(x1, x2) <https://docs.python.org/3/library/operator.html#operator.lt>`_
146146
- `operator.__lt__(x1, x2) <https://docs.python.org/3/library/operator.html#operator.__lt__>`_
147147

148-
- `x1 <= x2`: :meth:`array.__le__`
148+
- `x1 <= x2`: :meth:`.array.__le__`
149149

150150
- `operator.le(x1, x2) <https://docs.python.org/3/library/operator.html#operator.le>`_
151151
- `operator.__le__(x1, x2) <https://docs.python.org/3/library/operator.html#operator.__le__>`_
152152

153-
- `x1 > x2`: :meth:`array.__gt__`
153+
- `x1 > x2`: :meth:`.array.__gt__`
154154

155155
- `operator.gt(x1, x2) <https://docs.python.org/3/library/operator.html#operator.gt>`_
156156
- `operator.__gt__(x1, x2) <https://docs.python.org/3/library/operator.html#operator.__gt__>`_
157157

158-
- `x1 >= x2`: :meth:`array.__ge__`
158+
- `x1 >= x2`: :meth:`.array.__ge__`
159159

160160
- `operator.ge(x1, x2) <https://docs.python.org/3/library/operator.html#operator.ge>`_
161161
- `operator.__ge__(x1, x2) <https://docs.python.org/3/library/operator.html#operator.__ge__>`_
162162

163-
- `x1 == x2`: :meth:`array.__eq__`
163+
- `x1 == x2`: :meth:`.array.__eq__`
164164

165165
- `operator.eq(x1, x2) <https://docs.python.org/3/library/operator.html#operator.eq>`_
166166
- `operator.__eq__(x1, x2) <https://docs.python.org/3/library/operator.html#operator.__eq__>`_
167167

168-
- `x1 != x2`: :meth:`array.__ne__`
168+
- `x1 != x2`: :meth:`.array.__ne__`
169169

170170
- `operator.ne(x1, x2) <https://docs.python.org/3/library/operator.html#operator.ne>`_
171171
- `operator.__ne__(x1, x2) <https://docs.python.org/3/library/operator.html#operator.__ne__>`_

‎spec/API_specification/signatures/array_object.py

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,16 @@
1-
from ._types import array, dtype, Optional, Tuple, Union, Any, PyCapsule, Enum, ellipsis
2-
from ._types import device as Device
1+
from __future__ import annotations
32

4-
class array():
3+
from ._types import (array, dtype as Dtype, device as Device, Optional, Tuple,
4+
Union, Any, PyCapsule, Enum, ellipsis)
5+
6+
class _array():
57
def __init__(self) -> None:
68
"""
79
Initialize the attributes for the array object class.
810
"""
911

1012
@property
11-
def dtype() -> dtype:
13+
def dtype() -> Dtype:
1214
"""
1315
Data type of the array elements.
1416
@@ -99,7 +101,7 @@ def T() -> array:
99101
Returns
100102
-------
101103
out: array
102-
two-dimensional array whose first and last dimensions (axes) are permuted in reverse order relative to original array. The returned array must have the same data type as the original array.two-dimensional array whose first and last dimensions (axes) are permuted in reverse order relative to original array. The returned array must have the same data type as the original array.
104+
two-dimensional array whose first and last dimensions (axes) are permuted in reverse order relative to original array. The returned array must have the same data type as the original array.
103105
104106
105107
.. note::
@@ -987,3 +989,5 @@ def to_device(self: array, device: Device, /, *, stream: Optional[Union[int, Any
987989
.. note::
988990
If ``stream`` is given, the copy operation should be enqueued on the provided ``stream``; otherwise, the copy operation should be enqueued on the default stream/queue. Whether the copy is performed synchronously or asynchronously is implementation-dependent. Accordingly, if synchronization is required to guarantee data safety, this must be clearly explained in a conforming library's documentation.
989991
"""
992+
993+
array = _array

‎spec/Makefile

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33

44
# You can set these variables from the command line, and also
55
# from the environment for the first two.
6-
SPHINXOPTS ?=
6+
SPHINXOPTS ?= -W --keep-going
77
SPHINXBUILD ?= sphinx-build
88
SOURCEDIR = .
99
BUILDDIR = _build

‎spec/conf.py

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,34 @@
4848
napoleon_custom_sections = [('Returns', 'params_style')]
4949
default_role = 'code'
5050

51+
# nitpicky = True makes Sphinx warn whenever a cross-reference target can't be
52+
# found.
53+
nitpicky = True
54+
# autodoc wants to make cross-references for every type hint. But a lot of
55+
# them don't actually refer to anything that we have a document for.
56+
nitpick_ignore = [
57+
('py:class', 'array'),
58+
('py:class', 'device'),
59+
('py:class', 'dtype'),
60+
('py:class', 'NestedSequence'),
61+
('py:class', 'SupportsBufferProtocol'),
62+
('py:class', 'collections.abc.Sequence'),
63+
('py:class', "Optional[Union[int, float, Literal[inf, - inf, 'fro', 'nuc']]]"),
64+
('py:class', "Union[int, float, Literal[inf, - inf]]"),
65+
('py:class', 'PyCapsule'),
66+
('py:class', 'enum.Enum'),
67+
('py:class', 'ellipsis'),
68+
('py:class', 'finfo_object'),
69+
('py:class', 'iinfo_object'),
70+
]
71+
# In array_object.py we have to use aliased names for some types because they
72+
# would otherwise refer back to method objects of array
73+
autodoc_type_aliases = {
74+
'array': 'array',
75+
'Device': 'device',
76+
'Dtype': 'dtype',
77+
}
78+
5179
# Make autosummary show the signatures of functions in the tables using actual
5280
# Python syntax. There's currently no supported way to do this, so we have to
5381
# just patch out the function that processes the signatures. See

0 commit comments

Comments
 (0)
0