Minor doc markup polish

Author: hynek

.github/CONTRIBUTING.rst

@@ -1,7 +1,7 @@
 How To Contribute
 =================
 
-First off, thank you for considering contributing to ``argon2-cffi``!
+First off, thank you for considering contributing to *argon2-cffi*!
 It's people like *you* who make it such a great tool for everyone.
 
 This document intends to make contribution more accessible by codifying tribal knowledge and expectations.
@@ -96,55 +96,55 @@ Documentation
 
      - Added ``argon2_cffi.func()`` that does foo.
        It's pretty cool.
-       [`#1 <https://github.com/hynek/argon2_cffi/pull/1>`_]
+       `#1 <https://github.com/hynek/argon2_cffi/pull/1>`_
      - ``argon2_cffi.func()`` now doesn't crash the Large Hadron Collider anymore.
        That was a nasty bug!
-       [`#2 <https://github.com/hynek/argon2_cffi/pull/2>`_]
+       `#2 <https://github.com/hynek/argon2_cffi/pull/2>`_
 
 
 Local Development Environment
 -----------------------------
 
 You can (and should) run our test suite using tox_.
 However, you’ll probably want a more traditional environment as well.
-We highly recommend to develop using the latest Python 3 release because ``argon2_cffi`` tries to take advantage of modern features whenever possible.
+We highly recommend to develop using the latest Python 3 release because *argon2-cffi* tries to take advantage of modern features whenever possible.
 
 First create a `virtual environment <https://virtualenv.pypa.io/>`_.
 It’s out of scope for this document to list all the ways to manage virtual environments in Python, but if you don’t already have a pet way, take some time to look at tools like `pew <https://github.com/berdario/pew>`_, `virtualfish <https://virtualfish.readthedocs.io/>`_, and `virtualenvwrapper <https://virtualenvwrapper.readthedocs.io/>`_.
 
-Next, get an up to date checkout of the ``argon2_cffi`` repository:
+Next, get an up to date checkout of the *argon2-cffi* repository:
 
 .. code-block:: bash
 
-    $ git clone [email protected]:hynek/argon2_cffi.git
+    $ git clone [email protected]:hynek/argon2-cffi.git
 
 or if you want to use git via ``https``:
 
 .. code-block:: bash
 
-    $ git clone https://github.com/hynek/argon2_cffi.git
+    $ git clone https://github.com/hynek/argon2-cffi.git
 
-Change into the newly created directory and **after activating your virtual environment** install an editable version of ``argon2_cffi`` along with its tests and docs requirements:
+Change into the newly created directory and **after activating your virtual environment** install an editable version of *argon2-cffi* along with its tests and docs requirements:
 
-- First you have to make sure, that our git submodules are up to date and the Argon2 extension is built:
+- First you have to make sure, that our git submodules are up to date and the *Argon2* extension is built:
 
   #. ``git submodule init`` (to initialize git submodule mechanics)
-  #. ``git submodule update`` (to update the vendored Argon2 C library to the version ``argon2_cffi`` is currently packaging)
+  #. ``git submodule update`` (to update the vendored *Argon2* C library to the version *argon2-cffi* is currently packaging)
   #. ``python setup.py build`` (to build the CFFI module)
 
-  One of the environments requires a system-wide installation of Argon2.
+  One of the environments requires a system-wide installation of *Argon2*.
   On macOS, it's available in Homebrew (`brew install argon2`, but you also will have to update your `LDFLAGS` so you compiler finds it) and recent Ubuntus (zesty and later) ship it too.
 
 
-- Next (re-)install ``argon2_cffi`` along with its developement requirements:
+- Next (re-)install *argon2-cffi* along with its developement requirements:
 
   .. code-block:: bash
 
       $ pip install -e '.[dev]'
 
 ****
 
-**Whenever the Argon2 C code changes**: you will have to perform the steps above again except of ``git submodule init``.
+**Whenever the *Argon2 C* code changes**: you will have to perform the steps above again except of ``git submodule init``.
 
 ****
 

AUTHORS.rst

@@ -1,30 +1,31 @@
 Credits & License
 =================
 
-``argon2-cffi`` is maintained by Hynek Schlawack and released under the `MIT license <https://github.com/hynek/argon2-cffi/blob/main/LICENSE>`_.
+*argon2-cffi* is maintained by Hynek Schlawack and released under the `MIT license <https://github.com/hynek/argon2-cffi/blob/main/LICENSE>`_.
 
 The development is kindly supported by `Variomedia AG <https://www.variomedia.de/>`_.
+Please consider `supporting me <https://hynek.me/say-thanks/>`_ too!
 
 A full list of contributors can be found in GitHub's `overview <https://github.com/hynek/argon2-cffi/graphs/contributors>`_.
 
 
 Vendored Code
 -------------
 
-Argon2
-^^^^^^
+*Argon2*
+^^^^^^^^
 
-The original Argon2 repo can be found at https://github.com/P-H-C/phc-winner-argon2/.
+The original *Argon2* repo can be found at https://github.com/P-H-C/phc-winner-argon2/.
 
-Except for the components listed below, the Argon2 code in this repository is copyright (c) 2015 Daniel Dinu, Dmitry Khovratovich (main authors), Jean-Philippe Aumasson and Samuel Neves, and under CC0_ license.
+Except for the components listed below, the *Argon2* code in this repository is copyright (c) 2015 Daniel Dinu, Dmitry Khovratovich (main authors), Jean-Philippe Aumasson and Samuel Neves, and under CC0_ license.
 
 The string encoding routines in src/encoding.c are copyright (c) 2015 Thomas Pornin, and under CC0_ license.
 
 The `BLAKE2 <https://www.blake2.net>`_ code in ``src/blake2/`` is copyright (c) Samuel Neves, 2013-2015, and under CC0_ license.
 
-The authors of Argon2 also were very helpful to get the library to compile on ancient versions of Visual Studio for ancient versions of Python.
+The authors of *Argon2* also were very helpful to get the library to compile on ancient versions of Visual Studio for ancient versions of Python.
 
-The documentation also quotes frequently from the Argon2 paper_ to avoid mistakes by rephrasing.
+The documentation also quotes frequently from the *Argon2* paper_ to avoid mistakes by rephrasing.
 
 .. _CC0: https://creativecommons.org/publicdomain/zero/1.0/
 .. _paper: https://www.password-hashing.net/argon2-specs.pdf

CHANGELOG.rst

@@ -103,7 +103,7 @@ Backward-incompatible changes:
 - Python 3.4 is not supported anymore.
   It has been unsupported by the Python core team for a while now and its PyPI downloads are negligible.
 
-  It's very unlikely that ``argon2-cffi`` will break under 3.4 anytime soon, but we don't test it and don't ship binary wheels for it anymore.
+  It's very unlikely that *argon2-cffi* will break under 3.4 anytime soon, but we don't test it and don't ship binary wheels for it anymore.
 
 
 Deprecations:
@@ -213,7 +213,7 @@ Vendoring Argon2 @ `670229c <https://github.com/P-H-C/phc-winner-argon2/tree/670
 Changes:
 ^^^^^^^^
 
-- It is now possible to use the ``argon2-cffi`` bindings against an Argon2 library that is provided by the system.
+- It is now possible to use the *argon2-cffi* bindings against an Argon2 library that is provided by the system.
 
 
 ----

FAQ.rst

@@ -1,15 +1,15 @@
 Frequently Asked Questions
 ==========================
 
-I'm using ``bcrypt``/``PBKDF2``/``scrypt``/``yescrypt``, do I need to migrate?
+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.
+  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.
+  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``?
-   #. The Argon2 library had no concept of a "wrong password" error in the beginning.
+   #. 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.
 
       It goes without saying that it's impossible to switch now for backward-compatibility reasons.

docs/api.rst

@@ -3,7 +3,7 @@ API Reference
 
 .. module:: argon2
 
-``argon2-cffi`` comes with an high-level API and hopefully reasonable defaults for Argon2 parameters that result in a verification time of 40--50ms on recent-ish hardware.
+*argon2-cffi* comes with an high-level API and hopefully reasonable defaults for *Argon2* parameters that result in a verification time of 40--50ms on recent-ish hardware.
 
 .. warning::
 
@@ -117,7 +117,7 @@ The super low-level ``argon2_core()`` function is exposed too if you need access
 
 .. autofunction:: core
 
-In order to use :func:`core`, you need access to ``argon2-cffi``'s FFI objects.
+In order to use :func:`core`, you need access to *argon2-cffi*'s FFI objects.
 Therefore it is OK to use ``argon2.low_level.ffi`` and ``argon2.low_level.lib`` when working with it:
 
 .. doctest::
@@ -155,15 +155,15 @@ Therefore it is OK to use ``argon2.low_level.ffi`` and ``argon2.low_level.lib``
   >>> out == argon2.low_level.hash_secret_raw(pwd, salt, 1, 8, 1, 8, Type.D)
   True
 
-All constants and types on ``argon2.low_level.lib`` are guaranteed to stay as long they are not altered by Argon2 itself.
+All constants and types on ``argon2.low_level.lib`` are guaranteed to stay as long they are not altered by *Argon2* itself.
 
 .. autofunction:: error_to_str
 
 
 Deprecated APIs
 ---------------
 
-These APIs are from the first release of ``argon2-cffi`` and proved to live in an unfortunate mid-level.
+These APIs are from the first release of *argon2-cffi* and proved to live in an unfortunate mid-level.
 On one hand they have defaults and check parameters but on the other hand they only consume byte strings.
 
 Therefore the decision has been made to replace them by a high-level (:class:`argon2.PasswordHasher`) and a low-level (:mod:`argon2.low_level`) solution.

docs/argon2.rst

@@ -1,18 +1,18 @@
-What is Argon2?
-===============
+What is *Argon2*?
+=================
 
 .. note::
 
   **TL;DR**: Use :class:`argon2.PasswordHasher` with its default parameters to securely hash your passwords.
 
   You do **not** need to read or understand anything below this box.
 
-Argon2 is a secure password hashing algorithm.
+*Argon2* is a secure password hashing algorithm.
 It is designed to have both a configurable runtime as well as memory consumption.
 
 This means that you can decide how long it takes to hash a password and how much memory is required.
 
-Argon2 comes in three variants:
+*Argon2* comes in three variants:
 
 Argon2d
   is faster and uses data-depending memory access, which makes it less suitable for hashing secrets and more suitable for cryptocurrencies and applications with no threats from side-channel timing attacks.
@@ -55,7 +55,7 @@ The `Password Hashing Competition`_ took place between 2012 and 2015 to find a n
 Previously the NIST was in charge but after certain events and revelations_ their integrity has been put into question by the general public.
 So a group of independent cryptographers and security researchers came together.
 
-In the end, Argon2 was announced_ as the winner.
+In the end, *Argon2* was announced_ as the winner.
 
 .. _Password Hashing Competition: https://www.password-hashing.net/
 .. _revelations: https://en.wikipedia.org/wiki/Dual_EC_DRBG

docs/backward-compatibility.rst

@@ -1,7 +1,7 @@
 Backward Compatibility
 ======================
 
-``argon2-cffi`` has a very strong backward compatibility policy.
+*argon2-cffi* has a very strong backward compatibility policy.
 Generally speaking, you shouldn't ever be afraid of updating.
 
 If breaking changes are needed do be done, they are:

docs/cli.rst

@@ -1,8 +1,8 @@
 CLI
 ===
 
-To aid you with finding the parameters, ``argon2-cffi`` offers a CLI interface that can be accessed using ``python -m argon2``.
-It will benchmark Argon2’s password *verification* in the current environment.
+To aid you with finding the parameters, *argon2-cffi* offers a CLI interface that can be accessed using ``python -m argon2``.
+It will benchmark *Argon2*’s password *verification* in the current environment.
 You can use command line arguments to set hashing parameters:
 
 .. code-block:: text

docs/installation.rst

@@ -1,58 +1,58 @@
 Installation
 ============
 
-Using the Vendored Argon2
--------------------------
+Using the Vendored *Argon2*
+---------------------------
 
 .. code-block:: bash
 
   python -m pip install argon2-cffi
 
 should be all it takes.
 
-But since ``argon2-cffi`` vendors Argon2's C code by default, it can lead to complications depending on the platform.
+But since *argon2-cffi* vendors *Argon2*'s C code by default, it can lead to complications depending on the platform.
 
 The C code is known to compile and work on all common platforms (including x86, ARM, and PPC).
 On x86, an SSE2_-optimized version is used.
 
-If something goes wrong, please try to update your ``cffi``, ``pip`` and ``setuptools`` first:
+If something goes wrong, please try to update your *cffi*, *pip* and *setuptools* packages first:
 
 .. code-block:: bash
 
   python -m pip install -U cffi pip setuptools
 
 
-Overall this should be the safest bet because ``argon2-cffi`` has been specifically tested against the vendored version.
+Overall this should be the safest bet because *argon2-cffi* has been specifically tested against the vendored version.
 
 
 Wheels
 ^^^^^^
 
 Binary `wheels <https://pythonwheels.com>`_ for macOS, Windows, and Linux are provided on PyPI_.
-With a recent-enough ``pip`` and ``setuptools``, they should be used automatically.
+With a recent-enough *pip* and *setuptools*, they should be used automatically.
 
 
 Source Distribution
 ^^^^^^^^^^^^^^^^^^^
 
 A working C compiler and `CFFI environment`_ are required.
-If you've been able to compile Python CFFI extensions before, ``argon2-cffi`` should install without any problems.
+If you've been able to compile Python CFFI extensions before, *argon2-cffi* should install without any problems.
 
 
-Using a System-wide Installation of Argon2
-------------------------------------------
+Using a System-wide Installation of *Argon2*
+--------------------------------------------
 
-If you set ``ARGON2_CFFI_USE_SYSTEM`` to ``1`` (and *only* ``1``), ``argon2-cffi`` will not build its bindings.
-However binary wheels are preferred by ``pip`` and Argon2 gets installed along with ``argon2-cffi`` anyway.
+If you set ``ARGON2_CFFI_USE_SYSTEM`` to ``1`` (and *only* ``1``), *argon2-cffi* will not build its bindings.
+However binary wheels are preferred by *pip* and *Argon2* gets installed along with *argon2-cffi* anyway.
 
-Therefore you also have to instruct ``pip`` to use a source distribution:
+Therefore you also have to instruct *pip* to use a source distribution:
 
 .. code-block:: bash
 
   env ARGON2_CFFI_USE_SYSTEM=1 \
     python -m pip install --no-binary=argon2-cffi argon2-cffi
 
-This approach can lead to problems around your build chain and you can run into incompatibilities between Argon2 and ``argon2-cffi`` if the latter has been tested against a different version.
+This approach can lead to problems around your build chain and you can run into incompatibilities between *Argon2* and *argon2-cffi* if the latter has been tested against a different version.
 
 **It is your own responsibility to deal with these risks if you choose this path.**
 
@@ -67,9 +67,9 @@ This can go wrong and is problematic for cross-compiling.
 
 Therefore you can use the ``ARGON2_CFFI_USE_SSE2`` environment variable to control the process:
 
-- If you set it to ``1``, ``argon2-cffi`` will build **with** SSE2 support.
-- If you set it to ``0``, ``argon2-cffi`` will build **without** SSE2 support.
-- If you set it to anything else, it will be ignored and ``argon2-cffi`` will try to guess.
+- If you set it to ``1``, *argon2-cffi* will build **with** SSE2 support.
+- If you set it to ``0``, *argon2-cffi* will build **without** SSE2 support.
+- If you set it to anything else, it will be ignored and *argon2-cffi* will try to guess.
 
 Available since version 20.1.0.
 

docs/parameters.rst

@@ -4,16 +4,16 @@ Choosing Parameters
 .. note::
 
   You can probably just use :class:`argon2.PasswordHasher` with its default values and be fine.
-  But it's good to double check using ``argon2-cffi``'s :doc:`cli` client, whether its defaults are too slow or too fast for your use case.
+  But it's good to double check using *argon2-cffi*'s :doc:`cli` client, whether its defaults are too slow or too fast for your use case.
 
 Finding the right parameters for a password hashing algorithm is a daunting task.
-The authors of Argon2 specified a method in their `paper <https://github.com/P-H-C/phc-winner-argon2/blob/master/argon2-specs.pdf>`_, however some parts of it have been revised in the `RFC draft`_ for Argon2 that is currently being written.
+The authors of *Argon2* specified a method in their `paper <https://github.com/P-H-C/phc-winner-argon2/blob/master/argon2-specs.pdf>`_, however some parts of it have been revised in the `RFC draft`_ for *Argon2* that is currently being written.
 
 The current recommended best practice is as follow:
 
 #. Choose whether you want Argon2i, Argon2d, or Argon2id (``type``).
    If you don't know what that means, choose Argon2id (:attr:`argon2.Type.ID`).
-#. Figure out how many threads can be used on each call to Argon2 (``parallelism``, called "lanes" in the RFC).
+#. Figure out how many threads can be used on each call to *Argon2* (``parallelism``, called "lanes" in the RFC).
    They recommend twice as many as the number of cores dedicated to hashing passwords.
    :class:`~argon2.PasswordHasher` will *not* determine this for you and use a default value that you can find in the linked API docs.
 #. Figure out how much memory each call can afford (``memory_cost``).
@@ -27,14 +27,14 @@ The current recommended best practice is as follow:
    One `recommendation <https://web.archive.org/web/20160304024620/https://www.nccgroup.trust/us/about-us/newsroom-and-events/blog/2015/march/enough-with-the-salts-updates-on-secure-password-schemes/>`_ for concurent user logins is to keep it under 0.5 ms.
    The RFC recommends under 500 ms.
    The truth is somewhere between those two values: more is more secure, less is a better user experience.
-   ``argon2-cffi``'s defaults try to land somewhere in the middle and aim for ~50ms, but the actual time depends on your hardware.
+   *argon2-cffi*'s defaults try to land somewhere in the middle and aim for ~50ms, but the actual time depends on your hardware.
 
    Please note though, that even a verification time of 1 second won't protect you against bad passwords from the "top 10,000 passwords" lists that you can find online.
 #. Measure the time for hashing using your chosen parameters.
    Find a ``time_cost`` that is within your accounted time.
    If ``time_cost=1`` takes too long, lower ``memory_cost``.
 
-``argon2-cffi``'s :doc:`cli` will help you with this process.
+*argon2-cffi*'s :doc:`cli` will help you with this process.
 
 
 .. note::