Add keypair docs (#1482)

* Add keypair docs

* Fix typo

* Update docs/guide/generating_key_pair.rst

Co-authored-by: Franciszek Job <54181625+franciszekjob@users.noreply.github.com>

* Update docs/guide/generating_key_pair.rst

Co-authored-by: Franciszek Job <54181625+franciszekjob@users.noreply.github.com>

* Update docs/guide/generating_key_pair.rst

Co-authored-by: Franciszek Job <54181625+franciszekjob@users.noreply.github.com>

* Update docs/guide/generating_key_pair.rst

Co-authored-by: Franciszek Job <54181625+franciszekjob@users.noreply.github.com>

* Fix method imports

* Add link do eth keystore file docs

---------

Co-authored-by: Franciszek Job <54181625+franciszekjob@users.noreply.github.com>

Author: kkawula

docs/guide.rst

@@ -9,3 +9,4 @@ Guide
     guide/deploying_contracts
     guide/serialization
     guide/signing
+    guide/generating_key_pair

docs/guide/generating_key_pair.rst

@@ -0,0 +1,46 @@
+Generating a Key pair
+=====================
+
+Key pair
+--------
+
+The Key pair is a pair of private and public keys. The private key is used to sign transactions, and the public key is used to verify the signature.
+In the starknet.py you need to use the :class:`~starknet_py.net.signer.key_pair.KeyPair` class to be able to create an :class:`~starknet_py.net.account.account.Account` and :class:`~starknet_py.net.signer.stark_curve_signer.StarkCurveSigner` object.
+
+Generating random key pair
+--------------------------
+
+Method :meth:`~starknet_py.net.signer.stark_curve_signer.KeyPair.generate` allows to generate cryptographically strong pseudo-random numbers
+suitable for managing secrets such as account authentication, tokens, and similar.
+
+.. codesnippet:: ../../starknet_py/tests/e2e/docs/guide/test_key_pair.py
+    :language: python
+    :dedent: 4
+    :start-after: docs-generate: start
+    :end-before: docs-generate: end
+
+
+Creating key pair from private Key
+----------------------------------
+
+To create a key pair from a private key, use the :meth:`~starknet_py.net.signer.stark_curve_signer.KeyPair.from_private_key` method.
+
+
+.. codesnippet:: ../../starknet_py/tests/e2e/docs/guide/test_key_pair.py
+    :language: python
+    :dedent: 4
+    :start-after: docs-from-private-key: start
+    :end-before: docs-from-private-key: end
+
+Reading key pair from keystore file
+-----------------------------------
+
+Using :meth:`~starknet_py.net.signer.stark_curve_signer.KeyPair.from_keystore` method there is possibility to import a key pair from a keystore file.
+The keystore file should follow the `Ethereum keystore <https://github.com/ethereum/wiki/wiki/Web3-Secret-Storage-Definition#scrypt>`_ format.
+
+.. codesnippet:: ../../starknet_py/tests/e2e/docs/guide/test_key_pair.py
+    :language: python
+    :dedent: 4
+    :start-after: docs-from-keystore: start
+    :end-before: docs-from-keystore: end
+

starknet_py/tests/e2e/docs/guide/test_key_pair.py

@@ -0,0 +1,41 @@
+# pylint: disable=import-outside-toplevel
+import pytest
+
+from starknet_py.constants import FIELD_PRIME
+
+
+def test_generate_key_pair():
+    # docs-generate: start
+    from starknet_py.net.signer.key_pair import KeyPair
+
+    key_pair = KeyPair.generate()
+    # docs-generate: end
+
+    hex_private_key = hex(key_pair.private_key)[2:]
+    padded_hex_private_key = hex_private_key.zfill(64)
+    assert len(padded_hex_private_key) == 64
+    assert key_pair.private_key < FIELD_PRIME
+    assert key_pair.public_key < FIELD_PRIME
+
+
+def test_key_pair_from_private_key():
+    # docs-from-private-key: start
+    from starknet_py.net.signer.key_pair import KeyPair
+
+    key_pair = KeyPair.from_private_key("0x1234abcd")
+    # docs-from-private-key: end
+
+    assert isinstance(key_pair.public_key, int)
+    assert isinstance(key_pair.private_key, int)
+
+
+@pytest.mark.skip(reason="This test requires a keystore file")
+def test_key_pair_from_keystore():
+    # docs-from-keystore: start
+    from starknet_py.net.signer.key_pair import KeyPair
+
+    key_pair = KeyPair.from_keystore("path/to/keystore", "password")
+    # docs-from-keystore: end
+
+    assert isinstance(key_pair.public_key, int)
+    assert isinstance(key_pair.private_key, int)