97 lines
2.5 KiB
Python
97 lines
2.5 KiB
Python
"""A module for creating docstrings for sphinx ``data`` domains."""
|
|
|
|
import re
|
|
import textwrap
|
|
|
|
_docstrings_list = []
|
|
|
|
|
|
def add_newdoc(name, value, doc):
|
|
_docstrings_list.append((name, value, doc))
|
|
|
|
|
|
def _parse_docstrings():
|
|
type_list_ret = []
|
|
for name, value, doc in _docstrings_list:
|
|
s = textwrap.dedent(doc).replace("\n", "\n ")
|
|
|
|
# Replace sections by rubrics
|
|
lines = s.split("\n")
|
|
new_lines = []
|
|
indent = ""
|
|
for line in lines:
|
|
m = re.match(r'^(\s+)[-=]+\s*$', line)
|
|
if m and new_lines:
|
|
prev = textwrap.dedent(new_lines.pop())
|
|
if prev == "Examples":
|
|
indent = ""
|
|
new_lines.append(f'{m.group(1)}.. rubric:: {prev}')
|
|
else:
|
|
indent = 4 * " "
|
|
new_lines.append(f'{m.group(1)}.. admonition:: {prev}')
|
|
new_lines.append("")
|
|
else:
|
|
new_lines.append(f"{indent}{line}")
|
|
s = "\n".join(new_lines)
|
|
|
|
# Done.
|
|
type_list_ret.append(f""".. data:: {name}\n :value: {value}\n {s}""")
|
|
return "\n".join(type_list_ret)
|
|
|
|
|
|
add_newdoc('ArrayLike', 'typing.Union[...]',
|
|
"""
|
|
A `~typing.Union` representing objects that can be coerced into an `~numpy.ndarray`.
|
|
|
|
Among others this includes the likes of:
|
|
|
|
* Scalars.
|
|
* (Nested) sequences.
|
|
* Objects implementing the `~class.__array__` protocol.
|
|
|
|
See Also
|
|
--------
|
|
:term:`array_like`:
|
|
Any scalar or sequence that can be interpreted as an ndarray.
|
|
|
|
Examples
|
|
--------
|
|
.. code-block:: python
|
|
|
|
>>> import numpy as np
|
|
>>> import numpy.typing as npt
|
|
|
|
>>> def as_array(a: npt.ArrayLike) -> np.ndarray:
|
|
... return np.array(a)
|
|
|
|
""")
|
|
|
|
add_newdoc('DTypeLike', 'typing.Union[...]',
|
|
"""
|
|
A `~typing.Union` representing objects that can be coerced into a `~numpy.dtype`.
|
|
|
|
Among others this includes the likes of:
|
|
|
|
* :class:`type` objects.
|
|
* Character codes or the names of :class:`type` objects.
|
|
* Objects with the ``.dtype`` attribute.
|
|
|
|
See Also
|
|
--------
|
|
:ref:`Specifying and constructing data types <arrays.dtypes.constructing>`
|
|
A comprehensive overview of all objects that can be coerced into data types.
|
|
|
|
Examples
|
|
--------
|
|
.. code-block:: python
|
|
|
|
>>> import numpy as np
|
|
>>> import numpy.typing as npt
|
|
|
|
>>> def as_dtype(d: npt.DTypeLike) -> np.dtype:
|
|
... return np.dtype(d)
|
|
|
|
""")
|
|
|
|
_docstrings = _parse_docstrings()
|