SHA-1 is broken, run for the hills (#3417)
diff --git a/docs/hazmat/primitives/cryptographic-hashes.rst b/docs/hazmat/primitives/cryptographic-hashes.rst
index 34d88bc..d3e9eb4 100644
--- a/docs/hazmat/primitives/cryptographic-hashes.rst
+++ b/docs/hazmat/primitives/cryptographic-hashes.rst
@@ -79,21 +79,6 @@
.. _cryptographic-hash-algorithms:
-SHA-1
-~~~~~
-
-.. attention::
-
- NIST has deprecated SHA-1 in favor of the SHA-2 variants. New applications
- are strongly suggested to use SHA-2 over SHA-1.
-
-.. class:: SHA1()
-
- SHA-1 is a cryptographic hash function standardized by NIST. It produces an
- 160-bit message digest. Cryptanalysis of SHA-1 has demonstrated that it is
- vulnerable to practical collision attacks, though no actual collisions are
- publicly known.
-
SHA-2 family
~~~~~~~~~~~~
@@ -149,6 +134,22 @@
:raises ValueError: If the ``digest_size`` is invalid.
+SHA-1
+~~~~~
+
+.. warning::
+
+ SHA-1 is a deprecated hash algorithm that has practical known collision
+ attacks. You are strongly discouraged from using it. Existing applications
+ should strongly consider moving away.
+
+.. class:: SHA1()
+
+ SHA-1 is a cryptographic hash function standardized by NIST. It produces an
+ 160-bit message digest. Cryptanalysis of SHA-1 has demonstrated that it is
+ vulnerable to practical collision attacks, and collisions have been
+ demonstrated.
+
RIPEMD160
~~~~~~~~~