Adds first docs

Author: sobolevn

.travis.yml

@@ -15,7 +15,7 @@ install: poetry install
 script:
   - poetry run flake8 .
   - poetry run mypy classes tests/**/*.py
-  - poetry run pytest
+  - poetry run pytest . docs/pages
   - poetry run doc8 -q docs
   - poetry check
   - poetry run pip check

classes/typeclass.py

@@ -92,8 +92,7 @@ def __call__(
         We don't guarantee the order of types inside groups.
         Use correct types, do not rely on our order.
 
-        Callbacks
-        ~~~~~~~~~
+        .. rubric:: Callbacks
 
         Since, we define ``__call__`` method for this class,
         it can be used and typechecked everywhere,
@@ -238,8 +237,7 @@ def typeclass(
     then it will be called,
     otherwise the default implementation will be called instead.
 
-    Generics
-    ~~~~~~~~
+    .. rubric:: Generics
 
     We also support generic, but the support is limited.
     We cannot rely on type parameters of the generic type,
@@ -277,6 +275,8 @@ def typeclass(
     we would like to improve our support for specific generic instances
     like ``MyGeneric[int]`` only. But, that's the best we can do for now.
 
+    .. rubric:: Protocols
+
     We also support protocols. It has the same limitation as ``Generic`` types.
     It is also dispatched after all regular ``instance``s are checked.
 

docs/pages/concept.rst

@@ -1,2 +1,70 @@
-Typeclass: the concept
-======================
+The concept
+===========
+
+Typeclasses are another form of polymorphism
+that is widely used in some functional languages.
+
+What's the point?
+
+Well, we need to do different logic based on input type.
+
+Like ``len()`` function which
+works differently for ``"string"`` and ``[1, 2]``.
+Or ``+`` operator that works for numbers like "add"
+and for strings it works like "concatenate".
+
+Classes and interfaces
+~~~~~~~~~~~~~~~~~~~~~~
+
+Traditionally, object oriented languages solve it via classes.
+
+And classes are hard.
+They have internal state, inheritance, methods (including static ones),
+strong type, structure, class-level constants, life-cycle, and etc.
+
+Magic methods
+~~~~~~~~~~~~~
+
+That's why Python is not purely built around this idea.
+It also has protocols: ``__len__``, ``__iter__``, ``__add__``, etc.
+Which are called "magic mathods" most of the time.
+
+This really helps and keeps the language easy.
+But, have some serious problem:
+we cannot add new protocols / magic methods to the existing data types.
+
+You cannot add new methods to the ``list`` type (and that's a good thing!),
+you cannot also change how ``__len__`` for example work there.
+
+But, sometimes we really need this!
+One of the most simple example is ``json`` serialisation and deserialisation.
+Each type should be covered, each one works differently, they can nest.
+And moreover, it is 100% fine and expected
+to add your own types to this process.
+
+So, how does it work?
+
+
+Steps
+-----
+
+To use typeclasses you should understand these steps:
+
+.. mermaid::
+  :caption: Typeclass steps.
+
+   graph LR
+       F1["Typeclass definition"] --> F2["Instance definition"]
+       F2                         --> F2
+       F2                         --> F3["Calling"]
+
+# TODO: cover each steps
+# TODO: json example for simple types
+
+
+singledispatch
+--------------
+
+One may ask, what is the difference
+with `singledispatch <https://docs.python.org/3/library/functools.html#functools.singledispatch>`_
+function from the standard library?

docs/pages/typeclass.rst

@@ -1,2 +1,5 @@
 Typeclass
 =========
+
+.. automodule:: classes.typeclass
+   :members:

docs/pages/typesafety.rst

@@ -1,2 +1,48 @@
-Type safety
+Type-safety
 ===========
+
+We try to bring as much type safety as possible.
+
+However, there are some limitations.
+This section will guide you through both
+features and troubles of type-safe typeclasses in Python.
+
+
+Features
+--------
+
+First of all, we always check that the signature is the same for all cases.
+
+.. code:: python
+
+  >>> from classes import typeclass
+  >>> @typeclass
+  ... def example(instance, arg: int, *, keyword: str) -> bool:
+  ...     ...
+  ...
+  >>> @example.instance(str)
+  ... def _example_str(instance: str, arg: int, *, keyword: str) -> bool:
+  ...     return instance * arg + keyword
+  ...
+
+Let's look at this example closely:
+
+1. We create a typeclass with the signature that all cases must share:
+   except for the ``instance`` parameter, which is polymorphic.
+2. We check that return type of all cases match the original one:
+   ``bool`` in our particular case
+3. We check that ``instance`` has the correct type in ``_example_str``
+
+When calling typeclasses, we also do the type check:
+
+.. code:: python
+
+  >>> example('a', 3, keyword='b')
+  'aaab'
+
+Here are features that we support:
+
+1. Typechecker knows that we allow only defined instances
+   to be the first (or instance) parameter in a call.
+2. We also check that other parameters do exist in the original signature
+3. We check the return type: it matches that defined one in the signature

setup.cfg

@@ -56,6 +56,7 @@ norecursedirs = temp *.egg .eggs dist build docs .tox .git __pycache__
 # you an overhead. See `docs/template/development-process.rst`.
 addopts =
   --doctest-modules
+  --doctest-glob='*.rst'
   --cov=classes
   --cov-report=term:skip-covered
   --cov-report=html