docs: fix nitpicky build

hynek · Aug 15, 2023 · a1d48eb · a1d48eb
1 parent 18339bd
commit a1d48eb
Show file tree

Hide file tree

Showing 15 changed files with 114 additions and 60 deletions.
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
@@ -69,14 +69,23 @@ At this point,
 $ python -m pytest
 ```
 
-should work and pass, as should:
+should work and pass.
+
+For documentation, you can use:
+
+```console
+$ tox run -e docs-watch
+```
+
+This will build the documentation, and then watch for changes and rebuild it whenever you save a file.
+
+To just build the documentation and run doctests, use:
 
 ```console
-$ cd docs
-$ make html
+$ tox run -e docs
 ```
 
-The built documentation can then be found in `docs/_build/html/`.
+You will find the built documentation in `docs/_build/html`.
 
 To avoid committing code that violates our style guide, we strongly advise you to install [*pre-commit*] and its hooks:
 

diff --git a/.github/SECURITY.md b/.github/SECURITY.md
@@ -2,7 +2,11 @@
 
 ## Supported Versions
 
-We are following [CalVer](https://calver.org) with generous backward-compatibility guarantees. Therefore we only support the latest version.
+We follow [CalVer](https://calver.org) with generous backwards-compatibility guarantees.
+Therefore, we only support the latest version.
+
+That said, you shouldn't be afraid to upgrade if you're only using our documented public APIs and pay attention to `DeprecationWarning`s.
+Whenever there is a need to break compatibility, it is announced in the changelog and raises a `DeprecationWarning` for a year (if possible) before it's finally really broken.
 
 
 ## Security contact information

diff --git a/README.md b/README.md
@@ -9,7 +9,7 @@
 
 <!-- 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:
+[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:
 
 ```pycon
 >>> from argon2 import PasswordHasher
@@ -29,17 +29,16 @@ argon2.exceptions.VerifyMismatchError: The password does not match the supplied
 ```
 <!-- end-short -->
 
-## Project Information
+## Project Links
 
 - [**PyPI**](https://pypi.org/project/argon2-cffi/)
-- [**Source Code**](https://github.com/hynek/argon2-cffi)
+- [**GitHub**](https://github.com/hynek/argon2-cffi)
 - [**Documentation**](https://argon2-cffi.readthedocs.io/)
 - [**Changelog**](https://github.com/hynek/argon2-cffi/blob/main/CHANGELOG.md)
+- The low-level Argon2 CFFI bindings are maintained in the separate [*argon2-cffi-bindings*](https://github.com/hynek/argon2-cffi-bindings) project.
 
-The low-level Argon2 CFFI bindings are maintained in the separate [*argon2-cffi-bindings*](https://github.com/hynek/argon2-cffi-bindings) project.
 
-
-### Credits
+## Credits
 
 *argon2-cffi* is maintained by [Hynek Schlawack](https://hynek.me/).
 
@@ -48,7 +47,7 @@ The development is kindly supported by my employer [Variomedia AG](https://www.v
 A full list of contributors can be found in GitHub's [overview](https://github.com/hynek/argon2-cffi/graphs/contributors).
 
 
-### *argon2-cffi* for Enterprise
+## *argon2-cffi* for Enterprise
 
 Available as part of the Tidelift Subscription.
 

diff --git a/docs/api.rst b/docs/api.rst
@@ -148,7 +148,22 @@ Low Level
 .. automodule:: argon2.low_level
 
 .. autoclass:: Type
-  :members: D, I, ID
+
+   .. attribute:: D
+
+      Argon2\ **d** is faster and uses data-depending memory access.
+      That makes it less suitable for hashing secrets and more suitable for cryptocurrencies and applications with no threats from side-channel timing attacks.
+
+   .. attribute:: I
+
+      Argon2\ **i** uses data-independent memory access.
+      Argon2i is slower as it makes more passes over the memory to protect from tradeoff attacks.
+
+   .. attribute:: ID
+
+      Argon2\ **id** is a hybrid of Argon2i and Argon2d, using a combination of data-depending and data-independent memory accesses, which gives some of Argon2i's resistance to side-channel cache timing attacks and much of Argon2d's resistance to GPU cracking attacks.
+
+      .. versionadded:: 16.3.0
 
 .. autodata:: ARGON2_VERSION
 

diff --git a/docs/changelog.md b/docs/changelog.md
diff --git a/docs/conf.py b/docs/conf.py
@@ -49,6 +49,8 @@
 # directories to ignore when looking for source files.
 exclude_patterns = ["_build"]
 
+nitpick_ignore = []
+
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
 default_role = "any"

diff --git a/docs/index.md b/docs/index.md
@@ -1,6 +1,6 @@
 # *argon2-cffi*: Argon2 for Python
 
-Release **{sub-ref}`release`**  ([What's new?](changelog))
+Release **{sub-ref}`release`**  ([What's new?](https://github.com/hynek/argon2-cffi/blob/main/CHANGELOG.md))
 
 ```{include} ../README.md
 :end-before: <!-- end-short -->
@@ -19,18 +19,29 @@ api
 parameters
 cli
 faq
-changelog
 ```
 
 
-## Project Information
+## Project Links
 
 ```{include} ../README.md
-:start-after: '## Project Information'
+:start-after: '## Project Links'
 ```
 
 
 ## Indices and tables
 
 - {ref}`genindex`
 - {ref}`search`
+
+```{toctree}
+:hidden:
+:caption: Meta
+
+PyPI <https://pypi.org/project/argon2-cffi/>
+GitHub <https://github.com/hynek/argon2-cffi/>
+Changelog <https://github.com/hynek/argon2-cffi/blob/main/CHANGELOG.md>
+Contributing <https://github.com/hynek/argon2-cffi/blob/main/.github/CONTRIBUTING.md>
+Security Policy <https://github.com/hynek/argon2-cffi/blob/main/.github/SECURITY.md>
+Funding <https://hynek.me/say-thanks/>
+```
diff --git a/docs/parameters.md b/docs/parameters.md
@@ -12,12 +12,12 @@ It comes with two recommendations in [section 4](https://www.rfc-editor.org/rfc/
 
 Please use the {doc}`cli` interface together with its `--profile` argument to see if they work for you.
 
-______________________________________________________________________
+---
 
 If you need finer tuning, the current recommended best practice is as follow:
 
 1. Choose whether you want Argon2i, Argon2d, or Argon2id (`type`).
-   If you don't know what that means, choose Argon2id ({attr}`argon2.Type.ID`).
+   If you don't know what that means, choose Argon2id ({attr}`argon2.low_level.Type.ID`).
 
 2. Figure out how many threads can be used on each call to Argon2 (`parallelism`, called "lanes" in the RFC).
    They recommend 4 threads.

diff --git a/pyproject.toml b/pyproject.toml
@@ -44,12 +44,12 @@ dependencies = [
 [project.optional-dependencies]
 tests = ["hypothesis", "pytest"]
 docs = ["sphinx", "sphinx-notfound-page", "furo", "myst-parser"]
-dev = ["argon2-cffi[tests,docs]", "mypy"]
+dev = ["argon2-cffi[tests]", "mypy"]
 
 [project.urls]
 Documentation = "https://argon2-cffi.readthedocs.io/"
 Changelog = "https://github.com/hynek/argon2-cffi/blob/main/CHANGELOG.md"
-"Source Code" = "https://github.com/hynek/argon2-cffi"
+GitHub = "https://github.com/hynek/argon2-cffi"
 Funding = "https://github.com/sponsors/hynek"
 Tidelift = "https://tidelift.com/subscription/pkg/pypi-argon2-cffi?utm_source=pypi-argon2-cffi&utm_medium=pypi"
 

diff --git a/src/argon2/__init__.py b/src/argon2/__init__.py
@@ -81,3 +81,16 @@ def __getattr__(name: str) -> str:
         return meta["Author-email"].split("<", 1)[1].rstrip(">")
 
     return meta[dunder_to_metadata[name]]
+
+
+# Make nicer public names.
+__locals = locals()
+for __name in __all__:
+    if (
+        not isinstance(__locals[__name], int)
+        and not __name.startswith("__")
+        and not __name.islower()
+    ):
+        __locals[__name].__module__ = "argon2"
+del __locals
+del __name  # pyright: ignore[reportUnboundVariable]
diff --git a/src/argon2/_legacy.py b/src/argon2/_legacy.py
@@ -29,7 +29,8 @@ def hash_password(
     type: Type = Type.I,
 ) -> bytes:
     """
-    Legacy alias for :func:`hash_secret` with default parameters.
+    Legacy alias for :func:`argon2.low_level.hash_secret` with default
+    parameters.
 
     .. deprecated:: 16.0.0
         Use :class:`argon2.PasswordHasher` for passwords.
@@ -51,7 +52,8 @@ def hash_password_raw(
     type: Type = Type.I,
 ) -> bytes:
     """
-    Legacy alias for :func:`hash_secret_raw` with default parameters.
+    Legacy alias for :func:`argon2.low_level.hash_secret_raw` with default
+    parameters.
 
     .. deprecated:: 16.0.0
         Use :class:`argon2.PasswordHasher` for passwords.
@@ -67,7 +69,8 @@ def verify_password(
     hash: bytes, password: bytes, type: Type = Type.I
 ) -> Literal[True]:
     """
-    Legacy alias for :func:`verify_secret` with default parameters.
+    Legacy alias for :func:`argon2.low_level.verify_secret` with default
+    parameters.
 
     .. deprecated:: 16.0.0
         Use :class:`argon2.PasswordHasher` for passwords.

diff --git a/src/argon2/_password_hasher.py b/src/argon2/_password_hasher.py
@@ -195,7 +195,7 @@ def verify(
             because *hash* is not valid for *password*.
         :raises argon2.exceptions.VerificationError: If verification fails for
             other reasons.
-        :raises argon2.exceptions.InvalidHash: If *hash* is so clearly
+        :raises argon2.exceptions.InvalidHashError: If *hash* is so clearly
             invalid, that it couldn't be passed to Argon2.
 
         :return: ``True`` on success, raise

diff --git a/src/argon2/low_level.py b/src/argon2/low_level.py
@@ -46,28 +46,8 @@ class Type(Enum):
     """
 
     D = lib.Argon2_d
-    r"""
-    Argon2\ **d** 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.
-    """
     I = lib.Argon2_i  # noqa: E741
-    r"""
-    Argon2\ **i** uses data-independent memory access.  Argon2i is slower as
-    it makes more passes over the memory to protect from tradeoff attacks.
-    """
     ID = lib.Argon2_id
-    r"""
-    Argon2\ **id** is a hybrid of Argon2i and Argon2d, using a combination of
-    data-depending and data-independent memory accesses, which gives some of
-    Argon2i's resistance to side-channel cache timing attacks and much of
-    Argon2d's resistance to GPU cracking attacks.
-
-    That makes it the preferred type for password hashing and password-based
-    key derivation.
-
-    .. versionadded:: 16.3.0
-    """
 
 
 def hash_secret(
@@ -92,7 +72,8 @@ def hash_secret(
     :param Type type: Which Argon2 variant to use.
     :param int version: Which Argon2 version to use.
 
-    For an explanation of the Argon2 parameters see :class:`PasswordHasher`.
+    For an explanation of the Argon2 parameters see
+    :class:`argon2.PasswordHasher`.
 
     :rtype: bytes
 

diff --git a/src/argon2/profiles.py b/src/argon2/profiles.py
@@ -2,7 +2,7 @@
 
 """
 This module offers access to standardized parameters that you can load using
-:meth:`PasswordHasher.from_parameters()`. See the `source code
+:meth:`argon2.PasswordHasher.from_parameters()`. See the `source code
 <https://github.com/hynek/argon2-cffi/blob/main/src/argon2/profiles.py>`_ for
 concrete values and :doc:`parameters` for more information.
 

diff --git a/tox.ini b/tox.ini
@@ -58,17 +58,6 @@ install_command = pip install {opts} --no-deps {packages}
 commands_pre = pip install -I hypothesis pytest git+https://github.com/hynek/argon2-cffi-bindings
 
 
-[testenv:docs]
-description = Build docs and run doctests.
-# Keep base_python in-sync with .readthedocs.yaml and ci.yml/docs.
-base_python = py311
-extras = docs
-commands =
-    python -Im 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
-
-
 [testenv:pre-commit]
 description = Run all pre-commit hooks.
 skip_install = true
@@ -86,3 +75,33 @@ commands = mypy src
 description = Check only API types.
 deps = mypy
 commands = mypy tests/typing
+
+
+[testenv:docs]
+description = Build docs and run doctests.
+# Keep base_python in-sync with .readthedocs.yaml and ci.yml/docs.
+base_python = py311
+extras = docs
+commands =
+    python -Im doctest README.md
+    sphinx-build -W -n -b html -d {envtmpdir}/doctrees docs docs/_build/html
+    sphinx-build -W -n -b doctest -d {envtmpdir}/doctrees docs docs/_build/html
+
+[testenv:docs-watch]
+package = editable
+base_python = {[testenv:docs]base_python}
+extras = {[testenv:docs]extras}
+deps = watchfiles
+commands =
+    watchfiles \
+        --ignore-paths docs/_build/ \
+        'sphinx-build -W -n --jobs auto -b html -d {envtmpdir}/doctrees docs docs/_build/html' \
+        src \
+        docs \
+        README.md \
+        CHANGELOG.md
+
+[testenv:docs-linkcheck]
+base_python = {[testenv:docs]base_python}
+extras = {[testenv:docs]extras}
+commands = sphinx-build -W -b linkcheck -d {envtmpdir}/doctrees docs docs/_build/html