fixes

Signed-off-by: nstarman <nstarkman@protonmail.com>

.pre-commit-config.yaml

@@ -32,7 +32,7 @@ repos:
       - id: text-unicode-replacement-char
 
   - repo: https://github.com/PyCQA/autoflake
-    rev: v1.7.0
+    rev: v1.7.1
     hooks:
       - id: autoflake
         args:
@@ -116,3 +116,8 @@ repos:
         - --strict
         - --ignore-missing-imports
         - --exclude=/docs/
+
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.2.1
+    hooks:
+      - id: codespell

README.rst

@@ -54,7 +54,7 @@ Time to check these work:
     >>> np.concatenate((w1d, w1d))
     Wrap1D(x=array([0, 1, 2, 0, 1, 2]))
 
-|ufunc| also have a number of methods: 'at', 'accumulate', etc. The funtion
+|ufunc| also have a number of methods: 'at', 'accumulate', etc. The function
 dispatch mechanism in `NEP13
 <https://numpy.org/neps/nep-0013-ufunc-overrides.html>`_ says that  "If one of
 the input or output arguments implements __array_ufunc__, it is executed instead

docs/conf.py

@@ -55,6 +55,7 @@ def get_authors() -> set[str]:
 extensions = [
     "sphinx.ext.doctest",
     "sphinx_automodapi.automodapi",
+    "numpydoc",
     "pytest_doctestplus.sphinx.doctestplus",
 ]
 
@@ -73,6 +74,8 @@ def get_authors() -> set[str]:
 # This is added to the end of RST files - a good place to put substitutions to
 # be used globally.
 rst_epilog = """
+.. |overload_numpy| replace:: :mod:`overload_numpy`
+
 .. |TypeConstraint| replace:: :class:`~overload_numpy.constraints.TypeConstraint`
 .. |Invariant| replace:: :class:`~overload_numpy.constraints.Invariant`
 .. |Covariant| replace:: :class:`~overload_numpy.constraints.Covariant`
@@ -81,8 +84,10 @@ def get_authors() -> set[str]:
 
 .. |NumPyOverloader| replace:: :class:`~overload_numpy.overload.NumPyOverloader`
 
-
+.. |Numpy| replace:: :mod:`numpy`
+.. |numpy| replace:: :mod:`numpy`
 .. |ufunc| replace:: :class:`~numpy.ufunc`
+.. |ndarray| replace:: :class:`~numpy.ndarray`
 .. |array_function| replace:: ``__array_function__``
 .. _array_function: https://numpy.org/doc/stable/reference/arrays.classes.html#numpy.class.__array_function__
 .. |array_ufunc| replace:: ``__array_ufunc__``
@@ -91,10 +96,13 @@ def get_authors() -> set[str]:
 
 # intersphinx
 intersphinx_mapping = {
-    "python": (
-        "https://docs.python.org/3/",
-        (None, "http://data.astropy.org/intersphinx/python3.inv"),
+    "python": ("https://docs.python.org/3/", (None, "http://data.astropy.org/intersphinx/python3.inv")),
+    "pythonloc": (
+        "http://docs.python.org/",
+        (None, (pathlib.Path(__file__).parent.parent / "local" / "python3_local_links.inv").resolve()),
     ),
+    "numpy": ("https://numpy.org/doc/stable/", (None, "http://data.astropy.org/intersphinx/numpy.inv")),
+    "scipy": ("https://docs.scipy.org/doc/scipy/reference/", (None, "http://data.astropy.org/intersphinx/scipy.inv")),
 }
 
 # Show / hide TODO blocks
@@ -146,6 +154,21 @@ def get_authors() -> set[str]:
     "mapping": ":term:`python:mapping`",
 }
 
+# # Report warnings for all validation checks minus specified checsk.
+# numpydoc_validation_checks = {
+#     "all",
+#     "GL01",  # Docstring text (summary) should start in the line immediately after ...
+#     "GL08",  # - The object does not have a docstring  # TODO! rm when does docstring inheritance
+#     "SA01",  # - See Also section not found
+# }
+
+# numpydoc_validation_exclude = {
+#     r"docs\."
+#     r"NumPyOverloader\.get$",
+#     r"NumPyOverloader\.items$",
+# }
+
+
 # -- Project information ------------------------------------------------------
 
 # This does not *have* to match the package name, but typically does
@@ -161,6 +184,10 @@ def get_authors() -> set[str]:
 # The full version, including alpha/beta/rc tags.
 release = get_version("overload_numpy")
 
+# -- automodapi configuration ---------------------------------------------------
+
+# automodsumm_inherited_members = True
+
 
 # -- Options for HTML output ---------------------------------------------------
 

docs/contributing.rst

@@ -1,19 +1,21 @@
-.. _contributing:
+.. _overload_numpy-contributing:
 
 *****************
-How to contribute
+How to Contribute
 *****************
 
 We welcome contributions from anyone via pull requests on `GitHub
 <https://github.com/nstarman/overload_numpy>`_. If you don't feel comfortable
 modifying or adding functionality, we also welcome feature requests and bug
-reports as `GitHub issues <https://github.com/nstarman/overload_numpy/issues>`_.
+reports as `GitHub Issues <https://github.com/nstarman/overload_numpy/issues>`_.
 
-Developer documentation
+
+Developer Documentation
 =======================
 
 .. toctree::
     :maxdepth: 1
 
+    install
     testing
     docs

docs/getting_started.rst

@@ -0,0 +1,17 @@
+###############
+Getting started
+###############
+
+
+.. automodule:: overload_numpy.mixin
+
+
+Where to go from here?
+======================
+
+This page is meant to demonstrate a few initial things you may want to do with
+|overload_numpy|. There is much more functionality that you can discover by
+perusing the :ref:`user guide <overload_numpy-user-guide>`. Some other
+commonly-used functionality includes:
+
+* :ref:`Adding type constraints <overload_numpy-constraints>`

docs/index.rst

@@ -1,18 +1,60 @@
-##############
-Overload NumPy
-##############
+.. include:: references.txt
 
+############################
+Overload-NumPy Documentation
+############################
 
-.. automodule:: overload_numpy.mixin
+|NumPy| offers powerful methods to allow arguments of |NumPy| functions (and
+|ufunc| objects) to define how a given function operates on them. The details
+are specified in NEP13_ and NEP18_, but in summary: normally |NumPy| only works
+on an |ndarray| but with NEP13_/NEP18_ for a custom object, users can register
+overrides for a |NumPy| function and then use that function on that object (a
+quick example is outlined below). Plugging into the |NumPy| framework is
+convenient both for developers -- to let |NumPy| take care of the actual math --
+and users -- who get many things, not least of which is a familiar API. If all
+this sounds great, that's because it is. However, if you've read NEP13_/NEP18_
+then you know that making the |NumPy| bridge to your custom object and
+registering overrides is non-trivial. That's where |overload_numpy| comes in.
+|overload_numpy| offers convenient base classes for the |NumPy| bridge and
+powerful methods to register overrides for functions, |ufunc| objects, and even
+|ufunc| methods (e.g. ``.accumulate()``). The library is fully typed and
+(almost) fully ``c``-transpiled for speed.
 
+.. code-block:: python
+
+   from dataclasses import dataclass
+   import numpy as np
+
+   @dataclass
+   class ArrayWrapper:
+      x: np.ndarray
+
+      ... # lot's of non-trivial implementation details
+
+   aw = ArrayWrapper(np.arange(10))
+
+   np.add(aw, aw)  # returns ArrayWrapper([0, 2, ...])
+
+
+This package is being actively developed in a `public repository on GitHub
+<https://github.com/nstarman/overload_numpy/>`_, and we are always looking for
+new contributors! No contribution is too small, so if you have any trouble with
+this code, find a typo, or have requests for new content (tutorials or
+features), `open an issue on GitHub
+<https://github.com/nstarman/overload_numpy/issues>`_.
+
+
+.. ---------------------
+.. Nav bar (top of docs)
 
 .. toctree::
    :maxdepth: 1
    :titlesonly:
 
    install
-   contributing
+   getting_started
    src/index
+   contributing
 
 
 Contributors

docs/install.rst

@@ -1,6 +1,6 @@
 .. include:: references.txt
 
-.. overload_numpy-install:
+.. _overload_numpy-install:
 
 ************
 Installation
@@ -48,12 +48,20 @@ the cloned ``overload_numpy`` directory)
     python -m pip install [-e] .
 
 
+To ``c``-transpile and build wheels with ``mypyc``.
+
+.. code-block:: bash
+
+    python -m pip install [-e] . --install-option='--use-mypyc"
+
+
 Python Dependencies
 ===================
 
 This packages has the following dependencies:
 
 * `Python`_ >= 3.8
+* ``mypy_extensions`` >= 0.4.3  : for ``c``-transpilation
 
 Explicit version requirements are specified in the project `pyproject.toml
 <https://github.com/nstarman/overload_numpy/blob/main/pyproject.toml>`_. ``pip``

docs/references.txt

@@ -1 +1,3 @@
 .. _Python: http://www.python.org
+.. _NEP13: https://numpy.org/neps/nep-0013-ufunc-overrides.html
+.. _NEP18: https://numpy.org/neps/nep-0018-array-function-protocol.html

docs/src/constraints.rst

@@ -1,11 +1,15 @@
-.. _constraints:
+.. module:: overload_numpy.constraints
+    :noindex:
+
+.. _overload_numpy-constraints:
 
 ###############################################
 Type Constraints (`overload_numpy.constraints`)
 ###############################################
 
 .. automodule:: overload_numpy.constraints
 
+
 API
 ===
 

docs/src/conventions.rst

@@ -0,0 +1,13 @@
+.. _overload_numpy-conventions:
+
+###########
+Conventions
+###########
+
+Public API
+==========
+
+Some things in this package are public, others are not. This is how to tell:
+
+* If a module or package defines ``__all__``, that authoritatively defines the public interface.
+* If something begins with a leading underscore, it and its contents are private.

docs/src/index.rst

@@ -1,18 +1,26 @@
-.. _overload_numpy:
+.. _overload_numpy-user-guide:
 
-#################################
-Overload NumPy (`overload_numpy`)
-#################################
+##########
+User Guide
+##########
+
+The user guide contains exhaustive descriptions of all of the functions and
+classes available in ``overload_numpy``, with some inline narrative descriptions and
+demonstrations of functionality.
 
 .. toctree::
     :maxdepth: 1
 
+    conventions
+    mixin
+    register
     constraints
 
 
-.. _overload_numpy-api:
+Recent additions and changes
+============================
 
-API
-===
+.. toctree::
+    :maxdepth: 2
 
-.. automodapi:: overload_numpy
+    whatsnew/index

docs/src/mixin.rst

@@ -0,0 +1,18 @@
+.. _overload_numpy-mixin:
+
+######################################
+Mixin Bridges (`overload_numpy.mixin`)
+######################################
+
+Mixins for adding |array_ufunc|_ &/or |array_function|_ methods.
+Choose the one that's best suited for your needs.
+
+
+API
+===
+
+.. automodapi:: overload_numpy
+    :no-main-docstr:
+    :no-heading:
+    :noindex:
+    :skip: NumPyOverloader

docs/src/register.rst

@@ -0,0 +1,31 @@
+.. module:: overload_numpy.overload
+
+.. _overload_numpy-overload:
+
+#############################################
+Override Registry (`overload_numpy.overload`)
+#############################################
+
+.. automodule:: overload_numpy.overload
+
+
+
+A note about |ufunc|
+====================
+
+When registering a |ufunc| override a wrapper object is returned instead of the
+original function. On these objects only the ``__call__`` and ``register``
+methods are public API.
+
+
+
+API
+===
+
+.. automodapi:: overload_numpy
+    :no-main-docstr:
+    :no-heading:
+    :noindex:
+    :skip: NPArrayOverloadMixin
+    :skip: NPArrayFuncOverloadMixin
+    :skip: NPArrayUFuncOverloadMixin

docs/testing.rst

@@ -40,3 +40,6 @@ Then you can run the tests with:
 ::
 
     pytest overload_numpy
+
+
+==

pyproject.toml

@@ -21,7 +21,6 @@
   ]
   dependencies = [
     "mypy_extensions>=0.4.3",
-    "numpy>=1.18",
   ]
 
 [project.optional-dependencies]