Deploying to gh-pages from @ 45b64d2 🚀

Author: lucascolley

_sources/contributing.md.txt

@@ -6,11 +6,14 @@ converting code to consume the standard.
 
 Thanks to [all contributors](contributors.md) so far!
 
-## How to contribute a function
+## How to contribute a new function
 
 - [Open an issue](https://github.com/data-apis/array-api-extra/issues/new) to
-  propose the new function.
-- Add the implementation of your function to `src/array_api_extra/_funcs.py`.
+  propose the new function. You may want to wait for initial feedback on the
+  issue before diving into an implementation. Feel free to skip this step if
+  there is already an open issue for the function.
+- Add the implementation of your function to
+  `src/array_api_extra/_lib/_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.
@@ -20,6 +23,33 @@ Thanks to [all contributors](contributors.md) so far!
 - Add your function to `docs/api-reference.md`.
 - [Make a PR!](https://github.com/data-apis/array-api-extra/pulls)
 
+## How to add delegation to a function
+
+See [the tracker for adding delegation][delegation-tracker].
+
+[delegation-tracker]: https://github.com/data-apis/array-api-extra/issues/100
+
+- If you would like to discuss the task before diving into the implementation,
+  click on the three dots next to the function on the tracker issue, and choose
+  "Convert to sub-issue".
+- Create a function in `src/array_api_extra/_delegation.py` with a signature
+  matching the function in `src/array_api_extra/_lib/_funcs.py`, and move the
+  docstring to the new function. Leave a one-line docstring in `_funcs.py`,
+  pointing to `_delegation.py` to see the full docstring.
+- Also move the initial `array_namespace` call and any input validation over to
+  the new function.
+- Add delegation to backends using the `if _delegate` pattern. See
+  `src/array_api_extra/_lib/_backends.py` for the full list of backends we have
+  worked with so far.
+- After all delegation layers, return the result from the implementation in
+  `_funcs`.
+- Simplify the signature in `_funcs.py` to remove impossible arguments now that
+  it is only called internally via `_delegation`. For example, the `xp`
+  parameter can be changed from type `ModuleType | None` to `ModuleType`.
+- Don't worry if you are not sure how to do some of the above steps or think you
+  might have done something wrong -
+  [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

contributing.html

@@ -266,12 +266,15 @@ <h1>Contributing<a class="headerlink" href="#contributing" title="Link to this h
 have found themselves writing private array-agnostic functions in the process of
 converting code to consume the standard.</p>
 <p>Thanks to <a class="reference internal" href="contributors.html"><span class="std std-doc">all contributors</span></a> so far!</p>
-<section id="how-to-contribute-a-function">
-<h2>How to contribute a function<a class="headerlink" href="#how-to-contribute-a-function" title="Link to this heading">¶</a></h2>
+<section id="how-to-contribute-a-new-function">
+<h2>How to contribute a new function<a class="headerlink" href="#how-to-contribute-a-new-function" title="Link to this heading">¶</a></h2>
 <ul class="simple">
 <li><p><a class="reference external" href="https://github.com/data-apis/array-api-extra/issues/new">Open an issue</a> to
-propose the new function.</p></li>
-<li><p>Add the implementation of your function to <code class="docutils literal notranslate"><span class="pre">src/array_api_extra/_funcs.py</span></code>.</p>
+propose the new function. You may want to wait for initial feedback on the
+issue before diving into an implementation. Feel free to skip this step if
+there is already an open issue for the function.</p></li>
+<li><p>Add the implementation of your function to
+<code class="docutils literal notranslate"><span class="pre">src/array_api_extra/_lib/_funcs.py</span></code>.</p>
 <ul>
 <li><p>Ensure that your function includes type annotations and a
 <a class="reference external" href="https://numpydoc.readthedocs.io/en/latest/format.html">numpydoc-style docstring</a>.</p></li>
@@ -285,6 +288,32 @@ <h2>How to contribute a function<a class="headerlink" href="#how-to-contribute-a
 <li><p><a class="reference external" href="https://github.com/data-apis/array-api-extra/pulls">Make a PR!</a></p></li>
 </ul>
 </section>
+<section id="how-to-add-delegation-to-a-function">
+<h2>How to add delegation to a function<a class="headerlink" href="#how-to-add-delegation-to-a-function" title="Link to this heading">¶</a></h2>
+<p>See <a class="reference external" href="https://github.com/data-apis/array-api-extra/issues/100">the tracker for adding delegation</a>.</p>
+<ul class="simple">
+<li><p>If you would like to discuss the task before diving into the implementation,
+click on the three dots next to the function on the tracker issue, and choose
+“Convert to sub-issue”.</p></li>
+<li><p>Create a function in <code class="docutils literal notranslate"><span class="pre">src/array_api_extra/_delegation.py</span></code> with a signature
+matching the function in <code class="docutils literal notranslate"><span class="pre">src/array_api_extra/_lib/_funcs.py</span></code>, and move the
+docstring to the new function. Leave a one-line docstring in <code class="docutils literal notranslate"><span class="pre">_funcs.py</span></code>,
+pointing to <code class="docutils literal notranslate"><span class="pre">_delegation.py</span></code> to see the full docstring.</p></li>
+<li><p>Also move the initial <code class="docutils literal notranslate"><span class="pre">array_namespace</span></code> call and any input validation over to
+the new function.</p></li>
+<li><p>Add delegation to backends using the <code class="docutils literal notranslate"><span class="pre">if</span> <span class="pre">_delegate</span></code> pattern. See
+<code class="docutils literal notranslate"><span class="pre">src/array_api_extra/_lib/_backends.py</span></code> for the full list of backends we have
+worked with so far.</p></li>
+<li><p>After all delegation layers, return the result from the implementation in
+<code class="docutils literal notranslate"><span class="pre">_funcs</span></code>.</p></li>
+<li><p>Simplify the signature in <code class="docutils literal notranslate"><span class="pre">_funcs.py</span></code> to remove impossible arguments now that
+it is only called internally via <code class="docutils literal notranslate"><span class="pre">_delegation</span></code>. For example, the <code class="docutils literal notranslate"><span class="pre">xp</span></code>
+parameter can be changed from type <code class="docutils literal notranslate"><span class="pre">ModuleType</span> <span class="pre">|</span> <span class="pre">None</span></code> to <code class="docutils literal notranslate"><span class="pre">ModuleType</span></code>.</p></li>
+<li><p>Don’t worry if you are not sure how to do some of the above steps or think you
+might have done something wrong -
+<a class="reference external" href="https://github.com/data-apis/array-api-extra/pulls">make a PR!</a></p></li>
+</ul>
+</section>
 <section id="development-workflow">
 <h2>Development workflow<a class="headerlink" href="#development-workflow" title="Link to this heading">¶</a></h2>
 <p>If you are an experienced contributor to Python packages, feel free to develop
@@ -431,7 +460,8 @@ <h2>Development workflow<a class="headerlink" href="#development-workflow" title
           <div class="toc-tree">
             <ul>
 <li><a class="reference internal" href="#">Contributing</a><ul>
-<li><a class="reference internal" href="#how-to-contribute-a-function">How to contribute a function</a></li>
+<li><a class="reference internal" href="#how-to-contribute-a-new-function">How to contribute a new function</a></li>
+<li><a class="reference internal" href="#how-to-add-delegation-to-a-function">How to add delegation to a function</a></li>
 <li><a class="reference internal" href="#development-workflow">Development workflow</a></li>
 </ul>
 </li>