chore: upgrade docs tooling to latest stable; hide badges from the man page

docs/index.rst

@@ -1,7 +1,9 @@
 validators - Python Data Validation for Humans™
 ===============================================
 
-|PyCQA| |SAST| |Docs| |Version| |Downloads|
+.. only:: html
+
+   |PyCQA| |SAST| |Docs| |Version| |Downloads|
 
 .. raw:: html
 
@@ -36,10 +38,10 @@ Resources
 
    <!-- Original documentation URL :  https://python-validators.github.io/validators/ -->
 
--  `Documentation <https://nandgator.github.io/pyvalidators>`__
--  `Bugtracker <https://github.com/python-validators/validators/issues>`__
--  `Security <https://github.com/python-validators/validators/blob/master/SECURITY.md>`__
--  `Code <https://github.com/python-validators/validators/>`__
+- `Documentation <https://nandgator.github.io/pyvalidators>`__
+- `Bugtracker <https://github.com/python-validators/validators/issues>`__
+- `Security <https://github.com/python-validators/validators/blob/master/SECURITY.md>`__
+- `Code <https://github.com/python-validators/validators/>`__
 
 ..
 

docs/install_and_use.md

@@ -14,7 +14,8 @@ pip install validators
 
 ```python
 import validators
-print(validators.email('someone@example.com'))
+
+print(validators.email("someone@example.com"))
 ```
 
 ### To raise validation error

docs/install_and_use.rst

@@ -20,7 +20,8 @@ Usage
 .. code:: python
 
    import validators
-   print(validators.email('someone@example.com'))
+
+   print(validators.email("someone@example.com"))
 
 To raise validation error
 ~~~~~~~~~~~~~~~~~~~~~~~~~

mkdocs.yaml

@@ -48,7 +48,7 @@ plugins:
         python:
           options:
             show_root_heading: true
-          import:
+          inventories:
             - https://docs.python-requests.org/en/master/objects.inv
   - git-revision-date-localized
   - mike

package/export/__main__.py

@@ -4,6 +4,7 @@
 from ast import ImportFrom, parse
 from os.path import getsize
 from pathlib import Path
+from re import MULTILINE, sub
 from shutil import copy
 from subprocess import Popen  # nosec
 
@@ -53,6 +54,21 @@ def _gen_md_docs(source: Path, refs_path: Path):
     return mkdocs_build.returncode
 
 
+def _hide_badges_from_man(rst: str):
+    """Show the badge row (e.g. `|PyCQA| |SAST|`) only in html output.
+
+    The man builder renders every image as `[image: ...]` followed by its link target,
+    which is noise in a man page.
+    """
+    return sub(
+        r"^(\|[^|\n]+\|(?: \|[^|\n]+\|)*)$",
+        lambda match: f".. only:: html\n\n   {match.group(1)}",
+        rst,
+        count=1,
+        flags=MULTILINE,
+    )
+
+
 def _gen_rst_docs(source: Path, refs_path: Path, only_web: bool = False, only_man: bool = False):
     """Generate reStructuredText docs."""
     # external
@@ -64,9 +80,11 @@ def _gen_rst_docs(source: Path, refs_path: Path, only_web: bool = False, only_ma
 
     with open(source / "docs/index.rst", "wt") as idx_f:
         idx_f.write(
-            convert_file(source_file=source / "docs/index.md", format="md", to="rst").replace(
-                "\r\n",
-                "\n",  # remove carriage return in windows
+            _hide_badges_from_man(
+                convert_file(source_file=source / "docs/index.md", format="md", to="rst").replace(
+                    "\r\n",
+                    "\n",  # remove carriage return in windows
+                )
             )
             + "\n\n.. toctree::"
             + "\n   :hidden:"

pyproject.toml

@@ -54,23 +54,18 @@ crypto-eth-addresses = ["eth-hash[pycryptodome]>=0.7.0"]
 ##############################
 
 [dependency-groups]
-# The documentation and man page generation tooling is deliberately held to the versions
-# that produce the published output (the man page ships in distro packages). Newer
-# releases change the rendered output (e.g. man page markup, bundled pandoc) or break the
-# mkdocs configuration. Raise these bounds only together with a review of the regenerated
-# `docs/` and man page.
 docs-offline = [
-    "myst-parser>=3.0.1,<4",
-    "pypandoc-binary>=1.13,<1.14",
-    "sphinx>=7.1.2,<7.2",
-    "furo>=2024.8.6,<2025",
+    "myst-parser>=3.0.1",
+    "pypandoc-binary>=1.13",
+    "sphinx>=7.1.2",
+    "furo>=2024.8.6",
 ]
 docs-online = [
-    "mkdocs>=1.6.1,<2",
+    "mkdocs>=1.6.1",
     "mkdocs-git-revision-date-localized-plugin>=1.2.7",
-    "mkdocs-material>=9.5.34,<10",
-    "mkdocstrings[python]>=0.26.0,<1",
-    "mkdocstrings-python>=1.10.5,<2",
+    "mkdocs-material>=9.5.34",
+    "mkdocstrings[python]>=0.26.0",
+    "mkdocstrings-python>=1.14.0", # `inventories` option replaces `import`
     "mike>=2.1.3",
 ]
 package = ["build>=1.2.1"]
@@ -81,7 +76,7 @@ tooling = [
     "ruff>=0.6.3",
     "pyright>=1.1.378",
     "pytest>=9.0.3",
-    "pypandoc-binary>=1.13,<1.14", # helps with type checking
+    "pypandoc-binary>=1.13", # helps with type checking
 ]
 
 ####################
@@ -151,11 +146,6 @@ line-length = 100
 target-version = "py311"
 extend-exclude = ["**/__pycache__", ".pytest_cache", "site"]
 
-[tool.ruff.format]
-# Markdown files under docs/ are sources for the generated documentation and man page;
-# keep ruff (which can format Python code blocks in Markdown) away from them.
-exclude = ["*.md"]
-
 [tool.ruff.lint.isort]
 # case-sensitive = true
 combine-as-imports = true