Make plugin list in PDF docs readable (#9241)

The current PDF docs attempt to format the list of all plugins as a
table, without any word-wrapping of the plugin description. That results
in almost all the information getting cut off. This PR formats the same
information into more of a paragraph format for the PDF, with nothing
cut off.

Fixes #451

.github/workflows/update-plugin-list.yml

@@ -31,7 +31,7 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install packaging requests tabulate[widechars]
+          pip install packaging requests tabulate[widechars] tqdm
 
       - name: Update Plugin List
         run: python scripts/update-plugin-list.py

changelog/451.doc.rst

@@ -0,0 +1 @@
+The PDF documentation’s list of plugins doesn’t run off the page anymore.

scripts/update-plugin-list.py

@@ -1,10 +1,14 @@
 import datetime
 import pathlib
 import re
+from textwrap import dedent
+from textwrap import indent
 
 import packaging.version
 import requests
 import tabulate
+import wcwidth
+from tqdm import tqdm
 
 FILE_HEAD = r"""
 .. _plugin-list:
@@ -14,6 +18,11 @@ Plugin List
 
 PyPI projects that match "pytest-\*" are considered plugins and are listed
 automatically. Packages classified as inactive are excluded.
+
+.. The following conditional uses a different format for this list when
+   creating a PDF, because otherwise the table gets far too wide for the
+   page.
+
 """
 DEVELOPMENT_STATUS_CLASSIFIERS = (
     "Development Status :: 1 - Planning",
@@ -42,10 +51,15 @@ def escape_rst(text: str) -> str:
 def iter_plugins():
     regex = r">([\d\w-]*)</a>"
     response = requests.get("https://pypi.org/simple")
-    for match in re.finditer(regex, response.text):
+
+    matches = list(
+        match
+        for match in re.finditer(regex, response.text)
+        if match.groups()[0].startswith("pytest-")
+    )
+
+    for match in tqdm(matches, smoothing=0):
         name = match.groups()[0]
-        if not name.startswith("pytest-"):
-            continue
         response = requests.get(f"https://pypi.org/pypi/{name}/json")
         if response.status_code == 404:
             # Some packages, like pytest-azurepipelines42, are included in https://pypi.org/simple but
@@ -79,22 +93,47 @@ def iter_plugins():
         summary = escape_rst(info["summary"].replace("\n", ""))
         yield {
             "name": name,
-            "summary": summary,
+            "summary": summary.strip(),
             "last release": last_release,
             "status": status,
             "requires": requires,
         }
 
 
+def plugin_definitions(plugins):
+    """Return RST for the plugin list that fits better on a vertical page."""
+
+    for plugin in plugins:
+        yield dedent(
+            f"""
+            {plugin['name']}
+               *last release*: {plugin["last release"]},
+               *status*: {plugin["status"]},
+               *requires*: {plugin["requires"]}
+
+               {plugin["summary"]}
+            """
+        )
+
+
 def main():
     plugins = list(iter_plugins())
-    plugin_table = tabulate.tabulate(plugins, headers="keys", tablefmt="rst")
-    plugin_list = pathlib.Path("doc", "en", "reference", "plugin_list.rst")
+
+    reference_dir = pathlib.Path("doc", "en", "reference")
+
+    plugin_list = reference_dir / "plugin_list.rst"
     with plugin_list.open("w") as f:
         f.write(FILE_HEAD)
         f.write(f"This list contains {len(plugins)} plugins.\n\n")
-        f.write(plugin_table)
-        f.write("\n")
+        f.write(".. only:: not latex\n\n")
+
+        wcwidth  # reference library that must exist for tabulate to work
+        plugin_table = tabulate.tabulate(plugins, headers="keys", tablefmt="rst")
+        f.write(indent(plugin_table, "   "))
+        f.write("\n\n")
+
+        f.write(".. only:: latex\n\n")
+        f.write(indent("".join(plugin_definitions(plugins)), "  "))
 
 
 if __name__ == "__main__":