Fixes docs

Author: sobolevn

docs/index.rst

@@ -19,6 +19,7 @@ Contents
   pages/container.rst
   pages/result.rst
   pages/io.rst
+  pages/unsafe.rst
   pages/functions.rst
 
 .. toctree::

docs/pages/io.rst

@@ -101,6 +101,9 @@ See? It is now impossible for a pure function to use ``IO[bool]``.
 It is impossible to unwrap or get a value from this container.
 Once it is marked as ``IO`` it will never return to the pure state.
 
+Well, there's a hack actually:
+:py:func:`unsafe_perform_io <returns.unsafe.unsafe_perform_io>`
+
 It also needs to be explicitly mapped to produce new ``IO`` result:
 
 .. code:: python
@@ -148,37 +151,6 @@ There's one limitation in typing
 that we are facing right now
 due to `mypy issue <https://github.com/python/mypy/issues/3157>`_.
 
-unsafe
-------
-
-Sometimes you really need to get the raw value.
-For example:
-
-.. code:: python
-
-  def index_view(request, user_id):
-      user: IO[User] = get_user(user_id)
-      return render('index.html', { user: user })  # ???
-
-In this case your web-framework will not render your user correctly.
-Since it does not expect it to be wrapped inside ``IO`` containers.
-
-What to do? Use ``unsafe_perform_io``:
-
-.. code::
-
-  from returns.unsafe import unsafe_perform_io
-
-  def index_view(request, user_id):
-      user: IO[User] = get_user(user_id)
-      return render('index.html', { user: unsafe_perform_io(user) })  # Ok
-
-We need it as an escape and compatibility mechanism for our imperative shell.
-
-It is recommended
-to use `import-linter <https://github.com/seddonym/import-linter>`_
-to restrict imports from ``returns.unsafe`` expect the top-level modules.
-
 Further reading
 ---------------
 
@@ -193,6 +165,3 @@ API Reference
 
 .. automodule:: returns.io
    :members:
-
-.. automodule:: returns.unsafe
-   :members:

docs/pages/unsafe.rst

@@ -0,0 +1,39 @@
+unsafe
+======
+
+Sometimes you really need to get the raw value.
+For example:
+
+.. code:: python
+
+  def index_view(request, user_id):
+      user: IO[User] = get_user(user_id)
+      return render('index.html', { user: user })  # ???
+
+In this case your web-framework will not render your user correctly.
+Since it does not expect it to be wrapped inside ``IO`` containers.
+
+What to do? Use ``unsafe_perform_io``:
+
+.. code::
+
+  from returns.unsafe import unsafe_perform_io
+
+  def index_view(request, user_id):
+      user: IO[User] = get_user(user_id)
+      return render('index.html', { user: unsafe_perform_io(user) })  # Ok
+
+We need it as an escape and compatibility mechanism for our imperative shell.
+
+It is recommended
+to use `import-linter <https://github.com/seddonym/import-linter>`_
+to restrict imports from ``returns.unsafe`` expect the top-level modules.
+
+Inspired by Haskell's
+`unsafePerformIO <https://hackage.haskell.org/package/base-4.12.0.0/docs/System-IO-Unsafe.html#v:unsafePerformIO>`_
+
+API Reference
+-------------
+
+.. automodule:: returns.unsafe
+   :members:

returns/unsafe.py

@@ -5,14 +5,16 @@ def unsafe_perform_io(wrapped_in_io):
     """
     Compatibility utility and escape mechanism from IO world.
 
-    Just unwraps the internal value from IO container.
+    Just unwraps the internal value
+    from :py:class:`IO <returns.io.IO>` container.
     Should be used with caution!
     Since it might be overused by tired developers.
 
     It is recommended to have only one place (module / file)
-    in your program where you allow unsafe opetaions.
+    in your program where you allow unsafe operations.
 
     We recommend to use ``import-linter`` to enforce this rule:
+
     - https://github.com/seddonym/import-linter
 
     """