Merge pull request #8 from lucascolley/docs

Author: lucascolley

docs/contributing.md

@@ -0,0 +1,74 @@
+# Contributing
+
+Contributions are welcome from any "array-consuming" library contributors who
+have found themselves writing private array-agnostic functions in the process of
+converting code to consume the standard!
+
+## How to contribute a function
+
+- Add the implementation of your function to `src/array_api_extra/_funcs.py`.
+  - Ensure that your function includes type annotations and a
+    [numpydoc-style docstring](https://numpydoc.readthedocs.io/en/latest/format.html).
+  - Add your function to `__all__` at the top of the file.
+- Import your function to `src/array_api_extra/__init__.py` and add it to
+  `__all__` there.
+- Add a test class for your function in `tests/test_funcs.py`.
+- [Make a PR!](https://github.com/data-apis/array-api-extra/pulls)
+
+## Development workflow
+
+If you are an experienced contributor to Python packages, feel free to develop
+however you feel comfortable! However, if you would like some guidance,
+development of array-api-extra is made easy with
+[Pixi](https://pixi.sh/latest/):
+
+- [Clone the repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository)
+  at <https://github.com/data-apis/array-api-extra>.
+- `cd array-api-extra`.
+- [Install Pixi](https://pixi.sh/latest/#installation).
+- To enter a development environment:
+
+```
+pixi shell -e dev
+```
+
+- To run the tests:
+
+```
+pixi run test
+```
+
+- To build the docs locally:
+
+```
+pixi run docs
+```
+
+- To install a [pre-commit](https://pre-commit.com) hook and run the lint suite:
+
+```
+pixi run lint
+```
+
+- To enter an interactive Python prompt:
+
+```
+pixi run ipython
+```
+
+- To run individual parts of the lint suite separately:
+
+```
+pixi run pre-commit
+pixi run pylint
+pixi run mypy
+```
+
+Alternative environments are available with a subset of the dependencies and
+tasks available in the `dev` environment:
+
+```
+pixi shell -e docs
+pixi shell -e test
+pixi shell -e lint
+```

docs/index.md

@@ -4,8 +4,115 @@
 :maxdepth: 2
 :hidden:
 api-reference.md
+contributing.md
 ```
 
-```{include} ../README.md
-:start-after: <!-- SPHINX-START -->
+This is a library housing "array-agnostic" implementations of functions built on
+top of [the Python array API standard](https://data-apis.org/array-api/).
+
+The intended users of this library are "array-consuming" libraries which are
+using [array-api-compat](https://data-apis.org/array-api-compat/) to make their
+own library's functions array-agnostic. In this library, they will find a set of
+tools which provide _extra_ functionality on top of the array API standard,
+which other array-consuming libraries in a similar position have found useful
+themselves.
+
+(installation)=
+
+## Installation
+
+`array-api-extra` is available
+[on PyPI](https://pypi.org/project/array-api-extra/):
+
+```shell
+python -m pip install array-api-extra
+```
+
+(vendoring)=
+
+## Vendoring
+
+```{warning}
+This library currently provides no backwards-compatibility guarantees!
+If you require stability, it is recommended to vendor this library inside your own.
+```
+
+To vendor the library, clone
+[the repository](https://github.com/data-apis/array-api-extra) and copy
+`array_api_extra` into the appropriate place in your library, like:
+
+```
+cp -R array_api_extra/ mylib/vendored/array_api_extra
+```
+
+(usage)=
+
+## Usage
+
+Typical usage of this library looks like:
+
+```python
+import array_api_strict as xpx
+
+...
+xp = array_namespace(x)
+y = xp.sum(x)
+...
+return xpx.atleast_nd(y, ndim=2, xp=xp)
 ```
+
+```{note}
+Functions in this library assume input arrays *are arrays* (not "array-likes") and that
+the namespace passed as `xp` is compatible with the standard. This means that
+the namespace you pass as `xp` should come from array-api-compat's ``array_namespace``,
+or otherwise be compatible with the standard.
+```
+
+In the examples shown in the docstrings of functions from this library,
+[`array-api-strict`](https://data-apis.org/array-api-strict/) is used as the
+array namespace `xp`. In reality, code using this library will be written to
+work with any compatible array namespace as `xp`, not any particular
+implementation.
+
+(scope)=
+
+## Scope
+
+Functions that are in-scope for this library will:
+
+- Implement functionality which does not already exist in the array API
+  standard.
+- Implement functionality which may be generally useful across various
+  libraries.
+- Be implemented purely in terms of the array API standard.
+- Be implemented with type annotations and
+  [numpydoc-style docstrings](https://numpydoc.readthedocs.io/en/latest/format.html).
+- Be tested against `array-api-strict`.
+
+In particular, the following kinds of function are also in-scope:
+
+- Functions which implement
+  [array API standard extension](https://data-apis.org/array-api/2023.12/extensions/index.html)
+  functions in terms of functions from the base standard.
+- Functions which add functionality (e.g. extra parameters) to functions from
+  the standard.
+
+The following features are currently out-of-scope for this library:
+
+- Delegation to known, existing array libraries.
+  - It is quite simple to wrap functions in this library to also use existing
+    implementations where possible. Such delegation will not live in this
+    library for now, but the array-agnostic functions in this library could form
+    an array-agnostic backend for such delegating functions in the future, here
+    or elsewhere.
+- Functions which accept "array-like" input, or standard-incompatible
+  namespaces.
+  - It is possible to prepare input arrays and a standard-compatible namespace
+    via `array-api-compat` downstream in consumer libraries. Avoiding use of
+    `array-api-compat` in this library makes it easier to vendor and reduces
+    potential redundant calls to `xp.asarray` and `array_namespace`.
+  - For proposed alternatives to the `xp=xp` interface, see
+    [this issue](https://github.com/data-apis/array-api-extra/issues/6).
+- Functions which are specific to a particular domain.
+  - These functions may belong better in an array-consuming library which is
+    specific to that domain.