Closes #215, closes #54 (#233)

Author: sobolevn

.github/workflows/test.yml

@@ -47,7 +47,7 @@ jobs:
         poetry run flake8 .
         poetry run mypy classes ./tests/**/*.py
         poetry run codespell classes tests docs typesafety README.md CONTRIBUTING.md CHANGELOG.md
-        poetry run pytest classes tests docs/pages
+        poetry run pytest classes tests docs/pages README.md
         poetry run doc8 -q docs
         poetry run poetry check
         poetry run pip check

README.md

@@ -87,25 +87,26 @@ How would new API look like with this concept?
 ```python
 >>> from typing import Union
 >>> from classes import typeclass
+
 >>> @typeclass
 ... def to_json(instance) -> str:
 ...     """This is a typeclass definition to convert things to json."""
-...
+
 >>> @to_json.instance(int)
 ... @to_json.instance(float)
 ... def _to_json_int(instance: Union[int, float]) -> str:
 ...     return str(instance)
-...
+
 >>> @to_json.instance(bool)
 ... def _to_json_bool(instance: bool) -> str:
 ...     return 'true' if instance else 'false'
-...
+
 >>> @to_json.instance(list)
 ... def _to_json_list(instance: list) -> str:
 ...     return '[{0}]'.format(
 ...         ', '.join(to_json(list_item) for list_item in instance),
 ...     )
-...
+
 
 ```
 
@@ -126,9 +127,11 @@ Typeclass is represented as a regular function, so you can use it like one:
 And it easy to extend this typeclass with your own classes as well:
 
 ```python
->>> # Pretending to import the existing library from somewhere:
->>> # from to_json import to_json
+# Pretending to import the existing library from somewhere:
+# from to_json import to_json
+
 >>> import datetime as dt
+
 >>> @to_json.instance(dt.datetime)
 ... def _to_json_datetime(instance: dt.datetime) -> str:
 ...     return instance.isoformat()
@@ -142,6 +145,12 @@ That's how simple, safe, and powerful typeclasses are!
 Make sure to [check out our full docs](https://github.com/dry-python/classes) to learn more.
 
 
-## License
+## More!
+
+Want more?
+[Go to the docs!](https://classes.readthedocs.io)
+
 
-BSD 2-Clause
+<p align="center">&mdash; ⭐️ &mdash;</p>
+<p align="center"><i>Drylabs maintains dry-python and helps those who want to use it inside their organizations.</i></p>
+<p align="center"><i>Read more at <a href="https://drylabs.io">drylabs.io</a></i></p>

classes/_typeclass.py

@@ -112,6 +112,7 @@
 
     >>> assert example(WithField()) == 'with field'
 
+See our `official docs <https://classes.readthedocs.io>`_ to learn more!
 """
 
 from abc import get_cache_token
@@ -298,33 +299,8 @@ class _TypeClass(  # noqa: WPS214
     """
     That's how we represent typeclasses.
 
-    You should also use this type to annotate places
-    where you expect some specific typeclass to be used.
-
-    .. code:: python
-
-        >>> from typing import Callable
-        >>> from classes import typeclass
-
-        >>> @typeclass
-        ... def used(instance, other: int) -> int:
-        ...     '''Example typeclass to be used later.'''
-
-        >>> @used.instance(int)
-        ... def _used_int(instance: int, other: int) -> int:
-        ...     return instance + other
-
-        >>> def accepts_typeclass(
-        ...     callback: Callable[[int, int], int],
-        ... ) -> int:
-        ...     return callback(1, 3)
-
-        >>> assert accepts_typeclass(used) == 4
-
-    Take a note, that we structural subtyping here.
-    And all typeclasses that match ``Callable[[int, int], int]`` signature
-    will typecheck.
-
+    You probably don't need to use this type directly,
+    use its public methods and public :func:`~typeclass` constructor.
     """
 
     __slots__ = (
@@ -408,6 +384,30 @@ def __call__(
         Since, we define ``__call__`` method for this class,
         it can be used and typechecked everywhere,
         where a regular ``Callable`` is expected.
+
+        .. code:: python
+
+          >>> from typing import Callable
+          >>> from classes import typeclass
+
+          >>> @typeclass
+          ... def used(instance, other: int) -> int:
+          ...     '''Example typeclass to be used later.'''
+
+          >>> @used.instance(int)
+          ... def _used_int(instance: int, other: int) -> int:
+          ...     return instance + other
+
+          >>> def accepts_typeclass(
+          ...     callback: Callable[[int, int], int],
+          ... ) -> int:
+          ...     return callback(1, 3)
+
+          >>> assert accepts_typeclass(used) == 4
+
+        Take a note, that we use structural subtyping here.
+        And all typeclasses that match ``Callable[[int, int], int]`` signature
+        will typecheck.
         """
         self._control_abc_cache()
         instance_type = type(instance)

docs/_static/.gitkeep

@@ -0,0 +1,14 @@
+.globaltoc > p.caption {
+  display: block;
+  font-size: 1.05em;
+  font-weight: 700;
+  text-decoration: none;
+  margin-bottom: 1em;
+  border: 0;
+}
+
+/* For some reason it did not have a scroll attached. */
+
+.mermaid {
+  overflow: scroll;
+}

docs/_static/overrides.css

@@ -0,0 +1,5 @@
+{# layout.html #}
+{# Import the layout of the theme. #}
+{% extends "!layout.html" %}
+
+{% set css_files = css_files + ['_static/overrides.css'] %}

docs/_templates/layout.html

@@ -14,11 +14,23 @@ Contents
   :maxdepth: 2
   :caption: Userguide
 
+  pages/why.rst
   pages/concept.rst
-  pages/typeclass.rst
-  pages/typesafety.rst
+  pages/supports.rst
+  pages/generics.rst
+
+.. toctree::
+  :maxdepth: 1
+  :caption: Tooling
+
   pages/dry-python.rst
 
+.. toctree::
+  :maxdepth: 1
+  :caption: API
+
+  pages/api-docs.rst
+
 .. toctree::
   :maxdepth: 1
   :caption: Changelog