Add api docs

docs/api.rst

@@ -0,0 +1,54 @@
+.. _propcache-reference:
+
+============
+Reference
+============
+
+.. module:: propcache
+
+
+
+cached_property
+===============
+
+.. decorator:: cached_property(func)
+
+   This decorator functions exactly the same as the standard library
+   :func:`cached_property` decorator, but it's available in the
+   :mod:`propcache` module along with an accelerated Cython version.
+
+   As with the standard library version, the cached value is stored in
+   the instance's ``__dict__`` dictionary. To clear a cached value, you
+   can use the :meth:`del` operator on the instance's attribute or call
+   ``instance.__dict__.pop('attribute_name', None)``.
+
+under_cached_property
+=====================
+
+.. decorator:: under_cached_property(func)
+
+   Transform a method of a class into a property whose value is computed
+   only once and then cached as a private attribute. Similar to the
+   :func:`cached_property` decorator, but the cached value is stored
+   in the instance's ``_cache`` dictionary instead of ``__dict__``.
+
+   Example::
+
+       class MyClass:
+
+           def __init__(self, data: List[float]):
+               self._data = data
+               self._cache = {}
+
+           @cached_property
+           def calculated_data(self):
+               return expensive_operation(self._data)
+
+           def clear_cache(self):
+               self._cache.clear()
+
+       instance = MyClass([1.0, 2.0, 3.0])
+       print(instance.calculated_data)  # expensive operation
+
+       instance.clear_cache()
+       print(instance.calculated_data)  # expensive operation

docs/index.rst

@@ -18,6 +18,11 @@ The API is designed to be nearly identical to the built-in ``cached_property`` c
 except for the additional ``under_cached_property`` class which uses ``self._cache``
 instead of ``self.__dict__`` to store the cached values and prevents ``__set__`` from being called.
 
+API documentation
+------------------
+
+Open :ref:`propcache-api` for reading full list of available methods.
+
 Source code
 -----------
 
@@ -46,6 +51,11 @@ It's *Apache 2* licensed and freely available.
 
 Contents:
 
+.. toctree::
+   :maxdepth: 2
+
+   api
+
 .. toctree::
    :caption: What's new