Convert all top-level docs to Markdown

AUTHORS.md

@@ -0,0 +1,7 @@
+# Credits & License
+
+*argon2-cffi* is maintained by [Hynek Schlawack](https://hynek.me/) and released under the [MIT license](https://github.com/hynek/argon2-cffi/blob/main/LICENSE).
+
+The development is kindly supported by my employer [Variomedia AG](https://www.variomedia.de/), *argon2-cffi* [Tidelift subscribers](https://tidelift.com/subscription/pkg/pypi-argon2-cffi?utm_source=pypi-argon2-cffi&utm_medium=referral&utm_campaign=enterprise&utm_term=repo), and all my amazing [GitHub Sponsors](https://github.com/sponsors/hynek).
+
+A full list of contributors can be found in GitHub's [overview](https://github.com/hynek/argon2-cffi/graphs/contributors).

FAQ.md

@@ -0,0 +1,19 @@
+# Frequently Asked Questions
+
+I'm using *bcrypt* / *PBKDF2* / *scrypt* / *yescrypt*, do I need to migrate?
+
+: Using password hashes that aren't memory hard carries a certain risk but there's **no immediate danger or need for action**.
+If however you are deciding how to hash password *today*, *Argon2* is the superior, future-proof choice.
+
+  But if you already use one of the hashes mentioned in the question, you should be fine for the foreseeable future.
+  If you're using *scrypt* or *yescrypt*, you will be probably fine for good.
+
+Why do the `verify()` methods raise an Exception instead of returning `False`?
+
+: 1.  The *Argon2* library had no concept of a "wrong password" error in the beginning. Therefore when writing these bindings, an exception with the full error had to be raised so you could inspect what went actually wrong.
+
+      Changing that now would be a very dangerous break of backwards-compatibility.
+
+  2.  In my opinion, a wrong password should raise an exception such that it can't pass unnoticed by accident. See also The Zen of Python: "Errors should never pass silently."
+
+  3.  It's more [Pythonic](https://docs.python.org/3/glossary.html#term-EAFP).

README.md

@@ -0,0 +1,51 @@
+# *Argon2* for Python
+
+[![Documentation](https://img.shields.io/badge/Docs-Read%20The%20Docs-black)](https://argon2-cffi.readthedocs.io/)
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-C06524)](https://github.com/hynek/argon2-cffi/blob/main/LICENSE)
+
+[![PyPI version](https://img.shields.io/pypi/v/argon2-cffi)](https://pypi.org/project/argon2-cffi/)
+
+[![Downloads / Month](https://static.pepy.tech/personalized-badge/argon2-cffi?period=month&units=international_system&left_color=grey&right_color=blue&left_text=Downloads%20/%20Month)](https://pepy.tech/project/argon2-cffi)
+
+<!- begin-short ->
+
+[*Argon2*](https://github.com/p-h-c/phc-winner-argon2) won the [Password Hashing Competition](https://www.password-hashing.net/) and *argon2-cffi* is the simplest way to use it in Python and PyPy:
+
+```pycon
+>>> 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
+
+```
+<!- end-short ->
+
+## Project Information
+
+- **License**: [MIT](https://choosealicense.com/licenses/mit/)
+- **PyPI**: <https://pypi.org/project/argon2-cffi/>
+- **Source Code**: <https://github.com/hynek/argon2-cffi>
+- **Documentation**: <https://argon2-cffi.readthedocs.io/>
+- **Changelog**: <https://github.com/hynek/argon2-cffi/blob/main/CHANGELOG.md>
+- **Supported Python Versions**: 3.7 and later
+
+The low-level Argon2 CFFI bindings are maintained in the separate [*argon2-cffi-bindings*](https://github.com/hynek/argon2-cffi-bindings) project.
+
+
+### *argon2-cffi* for Enterprise
+
+Available as part of the Tidelift Subscription.
+
+The maintainers of *argon2-cffi* and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open-source packages you use to build your applications.
+Save time, reduce risk, and improve code health, while paying the maintainers of the exact packages you use.
+[Learn more.](https://tidelift.com/subscription/pkg/pypi-argon2-cffi?utm_source=undefined&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)

docs/changelog.md

@@ -0,0 +1,2 @@
+```{include} ../CHANGELOG.md
+```

docs/conf.py

@@ -8,13 +8,18 @@
 # ones.
 
 extensions = [
+    "myst_parser",
     "notfound.extension",
     "sphinx.ext.autodoc",
     "sphinx.ext.doctest",
     "sphinx.ext.intersphinx",
     "sphinx.ext.todo",
 ]
 
+myst_enable_extensions = [
+    "deflist",
+]
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
@@ -40,15 +45,6 @@
 # The short X.Y version.
 version = release.rsplit(".", 1)[0]
 
-rst_epilog = f"""
-.. |changelog| replace:: What’s new?
-.. _changelog: https://github.com/hynek/argon2-cffi/blob/{release}/CHANGELOG.md
-"""
-
-# In dev mode, always point to main branch. There's no tags yet.
-if release.endswith(".dev0"):
-    rst_epilog = rst_epilog.replace(release, "main")
-
 # Move type hints into the description block, instead of the func definition.
 autodoc_typehints = "description"
 autodoc_typehints_description_target = "documented"

docs/credits.md

@@ -0,0 +1,2 @@
+```{include} ../AUTHORS.md
+```

docs/faq.md

@@ -0,0 +1,2 @@
+```{include} ../FAQ.md
+```

docs/index.rst

@@ -2,12 +2,13 @@
 *argon2-cffi*: *Argon2* for Python
 ==================================
 
-Release v\ |release| (|changelog|_)
+Release v\ |release| (:doc:`What's new? <changelog>`)
 
 
-.. include:: ../README.rst
-   :start-after: -begin-short-
-   :end-before: -end-short-
+.. include:: ../README.md
+   :parser: myst_parser.sphinx_
+   :start-after: <!- begin-short ->
+   :end-before: <!- end-short ->
 
 
 User's Guide
@@ -22,11 +23,16 @@ User's Guide
    parameters
    cli
    faq
-   license
+   credits
+   changelog
 
-.. include:: ../README.rst
-   :start-after: -begin-meta-
-   :end-before: -end-meta-
+
+Project Information
+===================
+
+.. include:: ../README.md
+   :parser: myst_parser.sphinx_
+   :start-after: ## Project Information
 
 
 Indices and tables

pyproject.toml

@@ -41,12 +41,12 @@ classifiers = [
 ]
 dependencies = [
     "argon2-cffi-bindings",
-    "typing-extensions; python_version < '3.8'", # c.f. _typing.py module
+    "typing-extensions; python_version < '3.8'", # cf. _typing.py module
 ]
 
 [project.optional-dependencies]
 tests = ["hypothesis", "pytest"]
-docs = ["sphinx", "sphinx-notfound-page", "furo"]
+docs = ["sphinx", "sphinx-notfound-page", "furo", "myst-parser"]
 dev = ["argon2-cffi[tests,docs]", "mypy"]
 
 [project.urls]
@@ -64,10 +64,10 @@ raw-options = { version_scheme = "no-guess-dev" }
 
 
 [tool.hatch.metadata.hooks.fancy-pypi-readme]
-content-type = "text/x-rst"
+content-type = "text/markdown"
 
 [[tool.hatch.metadata.hooks.fancy-pypi-readme.fragments]]
-path = "README.rst"
+path = "README.md"
 
 
 [tool.pytest.ini_options]

tox.ini

@@ -33,7 +33,7 @@ description = Build docs and run doctests.
 basepython = python3.8
 extras = docs
 commands =
-    python -m doctest README.rst
+    python -m doctest README.md
     sphinx-build -W -b html -d {envtmpdir}/doctrees docs docs/_build/html
     sphinx-build -W -b doctest -d {envtmpdir}/doctrees docs docs/_build/html