Documentation Maintenance (#52)

* split navigation into named parts

* documented versioning and releases

* adjusted some docstrings for consistency

* expanded README blurb

* added conda-forge badge

Author: maxfischer2781

README.rst

@@ -10,6 +10,10 @@
     :alt: Available on PyPI
     :target: https://pypi.python.org/pypi/asyncstdlib/
 
+.. image:: https://anaconda.org/conda-forge/asyncstdlib/badges/version.svg
+    :alt: Available on Conda-Forge
+    :target: https://anaconda.org/conda-forge/asyncstdlib
+
 .. image:: https://img.shields.io/github/license/maxfischer2781/asyncstdlib.svg
     :alt: License
     :target: https://github.com/maxfischer2781/asyncstdlib/blob/master/LICENSE
@@ -24,3 +28,15 @@ and context managers.
 It is fully agnostic to ``async`` event loops and seamlessly works with
 ``asyncio``, third-party libraries such as ``trio``, as well as
 any custom ``async`` event loop.
+
+* Full set of ``async`` versions of advantageous standard library helpers,
+  such as ``zip``, ``map``, ``enumerate``, ``functools.reduce``,
+  ``itertools.tee``, ``itertools.groupby`` and many others.
+* Safe handling of ``async`` iterators to ensure prompt cleanup, as well as
+  various helpers to simplify safely using custom ``async`` iterators.
+* Small but powerful toolset to seamlessly integrate existing sync code
+  into ``async`` programs and libraries.
+
+Check out the `documentation`_ to get started or take a look around.
+
+.. _documentation: http://asyncstdlib.readthedocs.io/

asyncstdlib/asynctools.py

@@ -209,18 +209,18 @@ async def await_each(awaitables: Iterable[Awaitable[T]]) -> AsyncIterable[T]:
 
         import asyncstdlib as a
 
-         async def check1() -> bool:
-              ...
+        async def check1() -> bool:
+            ...
 
         async def check2() -> bool:
-              ...
+            ...
 
         async def check3() -> bool:
-              ...
+            ...
 
-         okay = await a.all(
-             a.await_each(
-                 [check1(), check2(), check3()]))
+        okay = await a.all(
+            a.await_each([check1(), check2(), check3()])
+        )
     """
     for awaitable in awaitables:
         yield await awaitable
@@ -329,12 +329,13 @@ async def compute_something_else() -> float:
 
 
 def sync(function: Callable[..., T]) -> Callable[..., Awaitable[T]]:
-    """
-    Wraps any Callable, which allows to use it as Awaitable object
-
-    :param function: can be any Callable
+    r"""
+    Wraps a callable to ensure its result can be ``await``\ ed
 
-    :raise TypeError: if function argument is not Callable
+    Useful to write :term:`async neutral` functions by wrapping callable arguments,
+    or to use synchronous functions where asynchronous ones are expected.
+    Wrapping a regular function defined using ``def`` or ``lambda`` makes it
+    behave roughly as if it were defined using ``async def`` instead.
 
     Example:
 

docs/index.rst

@@ -15,6 +15,10 @@ The missing ``async`` toolbox
     :alt: Available on PyPI
     :target: https://pypi.python.org/pypi/asyncstdlib/
 
+.. image:: https://anaconda.org/conda-forge/asyncstdlib/badges/version.svg
+    :alt: Available on Conda-Forge
+    :target: https://anaconda.org/conda-forge/asyncstdlib
+
 .. image:: https://img.shields.io/github/license/maxfischer2781/asyncstdlib.svg
     :alt: License
     :target: https://github.com/maxfischer2781/asyncstdlib/blob/master/LICENSE
@@ -28,6 +32,7 @@ The missing ``async`` toolbox
 
 .. toctree::
    :maxdepth: 1
+   :caption: The Async Toolbox
    :hidden:
 
    source/api/builtins
@@ -36,7 +41,14 @@ The missing ``async`` toolbox
    source/api/itertools
    source/api/asynctools
    source/glossary
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Development & Maintenance
+   :hidden:
+
    source/contributing
+   source/publishing
 
 The ``asyncstdlib`` library re-implements functions and classes of the Python
 standard library to make them compatible with ``async`` callables, iterables

docs/source/contributing.rst

@@ -1,5 +1,5 @@
 =======================
-Contributing Guidelines
+Contribution Guidelines
 =======================
 
 Contributions in code to the ``asyncstdlib`` library are highly welcome!

docs/source/publishing.rst

@@ -0,0 +1,61 @@
+=====================
+Versions and Releases
+=====================
+
+The ``asyncstdlib`` versioning closely follows
+versioning of the Python standard library.
+New versions are published via `PyPI`_ and `Conda-Forge`_
+for installation via ``pip`` and ``conda``.
+
+Versioning and feature coverage
+===============================
+
+The ``asyncstdlib`` mimics the versioning of the Python standard library:
+
+* *Major and Minor version* indicate which Python feature set is supported, and
+* *Patch version* indicates the iteration of this feature set.
+
+For example, ``asyncstdlib`` version 3.9.2 provides the feature set of Python 3.9,
+such as :py:func:`~asyncstdlib.functools.cache` added in 3.9
+and :py:func:`~asyncstdlib.functools.cached_property` added previously.
+
+The ``asyncstdlib.asynctools`` feature set does not follow a strict version model.
+New features may be added at minor or patch releases.
+
+Release workflow
+================
+
+.. note::
+
+    This section is only relevant for maintainers of ``asyncstdlib``.
+
+Releases are performed manually but should happen at least when
+an important fix or major feature is added.
+Most releases will bump the *patch* version number;
+only bump the *minor* or *major* version number to match a new Python release.
+
+1. Review all changes added by the new releases:
+    * Naming of functions/classes/parameters
+    * Docs are up to date and consistent
+    * Unittests cover all obvious cases
+
+2. Bump the version number:
+    * Adjust and commit ``asyncstdlib.__init__.__version__``
+    * Create a git tag such as ``git tag -a "v3.9.2" -m "description"``
+    * Push the commit and tags to github
+
+3. Publish to PyPI
+    * **You need maintainer access** on the `PyPI asyncstdlib project`_
+    * Check out the tagged version commit
+    * Run ``flit publish``
+
+4. Publish to Conda-Forge
+    * Create *a fork* of the `Conda-Forge asyncstdlib recipe`_
+    * In `./recipe/meta.yaml` adjust the ``version`` and ``sha256`` as the `PyPI release`_
+    * Create a Pull Request based on the fork
+
+.. _PyPI: https://pypi.org
+.. _Conda-Forge: https://conda-forge.org
+.. _`PyPI asyncstdlib project`: https://pypi.org/project/asyncstdlib/
+.. _`Conda-Forge asyncstdlib recipe`: https://github.com/conda-forge/asyncstdlib-feedstock
+.. _`PyPI release`: https://pypi.org/project/asyncstdlib/#files