From baead4e9e5e06a6440bedb16b61ac0d7df7c1a4b Mon Sep 17 00:00:00 2001
From: Hynek Schlawack <hs@ox.cx>
Date: Tue, 15 Aug 2023 08:23:13 +0200
Subject: [PATCH] Extract howto

---
 .gitignore    |  1 +
 docs/api.rst  | 38 --------------------------------------
 docs/howto.md | 38 ++++++++++++++++++++++++++++++++++++++
 docs/index.md |  1 +
 4 files changed, 40 insertions(+), 38 deletions(-)
 create mode 100644 docs/howto.md

diff --git a/.gitignore b/.gitignore
index e738125..d449d2a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -13,3 +13,4 @@
 __pycache__
 dist
 docs/_build/
+Justfile
diff --git a/docs/api.rst b/docs/api.rst
index dbcfe12..e5673ae 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -3,44 +3,6 @@ API Reference
 
 .. module:: argon2
 
-*argon2-cffi* comes with an high-level API and uses the officially recommended low-memory Argon2 parameters that result in a verification time of 40--50ms on recent-ish hardware.
-
-.. warning::
-
-   The current memory requirement is set to rather conservative 64 MB.
-   However, in memory constrained environments such as Docker containers that can lead to problems.
-   One possible non-obvious symptom are apparent freezes that are caused by swapping.
-
-   Please check :doc:`parameters` for more details.
-
-Unless you have any special needs, all you need to know is:
-
-.. doctest::
-
-  >>> from argon2 import PasswordHasher
-  >>> ph = PasswordHasher()
-  >>> hash = ph.hash("correct horse battery staple")
-  >>> hash  # doctest: +SKIP
-  '$argon2id$v=19$m=65536,t=3,p=4$MIIRqgvgQbgj220jfp0MPA$YfwJSVjtjSU0zzV/P3S9nnQ/USre2wvJMjfCIjrTQbg'
-  >>> ph.verify(hash, "correct horse battery staple")
-  True
-  >>> ph.check_needs_rehash(hash)
-  False
-  >>> ph.verify(hash, "Tr0ub4dor&3")
-  Traceback (most recent call last):
-    ...
-  argon2.exceptions.VerifyMismatchError: The password does not match the supplied hash
-
-
-A login function could thus look like this:
-
-.. literalinclude:: login_example.py
-   :language: python
-
-----
-
-While the :class:`PasswordHasher` class has the aspiration to be good to use out of the box, it has all the parametrization you'll need:
-
 .. autoclass:: PasswordHasher
   :members: from_parameters, hash, verify, check_needs_rehash
 
diff --git a/docs/howto.md b/docs/howto.md
new file mode 100644
index 0000000..ec9aac2
--- /dev/null
+++ b/docs/howto.md
@@ -0,0 +1,38 @@
+# How to Hash a Password
+
+*argon2-cffi* comes with an high-level API and uses the officially recommended low-memory Argon2 parameters that result in a verification time of 40--50ms on recent-ish hardware.
+
+:::{warning}
+The current memory requirement is set to rather conservative 64 MB.
+However, in memory constrained environments such as Docker containers that can lead to problems.
+One possible non-obvious symptom are apparent freezes that are caused by swapping.
+
+Please check {doc}`parameters` for more details.
+:::
+
+Unless you have any special requirements, all you need to know is:
+
+```python
+>>> from argon2 import PasswordHasher
+>>> ph = PasswordHasher()
+>>> hash = ph.hash("correct horse battery staple")
+>>> hash  # doctest: +SKIP
+'$argon2id$v=19$m=65536,t=3,p=4$MIIRqgvgQbgj220jfp0MPA$YfwJSVjtjSU0zzV/P3S9nnQ/USre2wvJMjfCIjrTQbg'
+>>> ph.verify(hash, "correct horse battery staple")
+True
+>>> ph.check_needs_rehash(hash)
+False
+>>> ph.verify(hash, "Tr0ub4dor&3")
+Traceback (most recent call last):
+...
+argon2.exceptions.VerifyMismatchError: The password does not match the supplied hash
+```
+
+A login function could thus look like this:
+
+```{literalinclude} login_example.py
+```
+
+---
+
+While the {class}`argon2.PasswordHasher` class has the aspiration to be good to use out of the box, it has all the parametrization you'll need.
diff --git a/docs/index.md b/docs/index.md
index 11f90b4..c5f7047 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -15,6 +15,7 @@ Release **{sub-ref}`release`**  ([What's new?](https://github.com/hynek/argon2-c
 
 argon2
 installation
+howto
 api
 parameters
 cli