scripts: Use pip-installed asciidoc

Fixes #7352, closes #6793

7 files changed, 22 insertions, 89 deletions

diff --git a/doc/install.asciidoc b/doc/install.asciidoc
index bbf7ab62f..da211d850 100644
--- a/doc/install.asciidoc
+++ b/doc/install.asciidoc
@@ -48,7 +48,7 @@ instructions!
 Note you'll need some basic libraries to use the virtualenv-installed PyQt:
 
 ----
-# apt install --no-install-recommends git ca-certificates python3 python3-venv asciidoc libglib2.0-0 libgl1 libfontconfig1 libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-randr0 libxcb-render-util0 libxcb-shape0 libxcb-xfixes0 libxcb-xinerama0 libxcb-xkb1 libxkbcommon-x11-0 libdbus-1-3 libyaml-dev gcc python3-dev libnss3 libasound2
+# apt install --no-install-recommends git ca-certificates python3 python3-venv libglib2.0-0 libgl1 libfontconfig1 libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-randr0 libxcb-render-util0 libxcb-shape0 libxcb-xfixes0 libxcb-xinerama0 libxcb-xkb1 libxkbcommon-x11-0 libdbus-1-3 libyaml-dev gcc python3-dev libnss3 libasound2
 ----
 
 // FIXME not needed anymore?
@@ -72,7 +72,7 @@ qutebrowser in a virtualenv>> with a newer PyQt/Qt binary instead.
 Note you'll need some basic libraries to use the virtualenv-installed PyQt:
 
 ----
-# apt install --no-install-recommends git ca-certificates python3 python3-venv asciidoc libglib2.0-0 libgl1 libfontconfig1 libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-randr0 libxcb-render-util0 libxcb-shape0 libxcb-xfixes0 libxcb-xinerama0 libxcb-xkb1 libxkbcommon-x11-0 libdbus-1-3 libyaml-dev gcc python3-dev libnss3 libasound2
+# apt install --no-install-recommends git ca-certificates python3 python3-venv libglib2.0-0 libgl1 libfontconfig1 libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-randr0 libxcb-render-util0 libxcb-shape0 libxcb-xfixes0 libxcb-xinerama0 libxcb-xkb1 libxkbcommon-x11-0 libdbus-1-3 libyaml-dev gcc python3-dev libnss3 libasound2
 ----
 
 Ubuntu 20.04 LTS / Linux Mint 20 (or newer)
@@ -93,7 +93,7 @@ Additional hints
   this for you):
 +
 ----
-# apt install --no-install-recommends asciidoc
+$ pip install -r misc/requirements/requirements-docs.txt  # or install asciidoc manually
 $ python3 scripts/asciidoc2html.py
 ----
 
@@ -514,18 +514,6 @@ You can create a simple wrapper script to start qutebrowser somewhere in your
 ~/path/to/qutebrowser/.venv/bin/python3 -m qutebrowser "$@"
 ----
 
-Building the docs
-~~~~~~~~~~~~~~~~~
-
-To build the documentation, install `asciidoc` (note that LaTeX which comes as
-optional/recommended dependency with some distributions is not required).
-
-Then, run:
-
-----
-$ python3 scripts/asciidoc2html.py
-----
-
 Updating
 ~~~~~~~~
 
diff --git a/misc/requirements/requirements-docs.txt b/misc/requirements/requirements-docs.txt
new file mode 100644
index 000000000..d2d35d758
--- /dev/null
+++ b/misc/requirements/requirements-docs.txt
@@ -0,0 +1,3 @@
+# This file is automatically generated by scripts/dev/recompile_requirements.py
+
+asciidoc==10.2.0
diff --git a/misc/requirements/requirements-docs.txt-raw b/misc/requirements/requirements-docs.txt-raw
new file mode 100644
index 000000000..1cd92d927
--- /dev/null
+++ b/misc/requirements/requirements-docs.txt-raw
@@ -0,0 +1 @@
+asciidoc
diff --git a/scripts/asciidoc2html.py b/scripts/asciidoc2html.py
index 291d48d5f..560faa0cd 100755
--- a/scripts/asciidoc2html.py
+++ b/scripts/asciidoc2html.py
@@ -48,13 +48,7 @@ class AsciiDoc:
         'install', 'stacktrace'
     ]
 
-    def __init__(self,
-                 asciidoc: Optional[str],
-                 asciidoc_python: Optional[str],
-                 website: Optional[str]) -> None:
-        self._cmd: Optional[List[str]] = None
-        self._asciidoc = asciidoc
-        self._asciidoc_python = asciidoc_python
+    def __init__(self, website: Optional[str]) -> None:
         self._website = website
         self._homedir: Optional[pathlib.Path] = None
         self._themedir: Optional[pathlib.Path] = None
@@ -63,7 +57,6 @@ class AsciiDoc:
 
     def prepare(self) -> None:
         """Get the asciidoc command and create the homedir to use."""
-        self._cmd = self._get_asciidoc_cmd()
         self._homedir = pathlib.Path(tempfile.mkdtemp())
         self._themedir = self._homedir / '.asciidoc' / 'themes' / 'qute'
         self._tempdir = self._homedir / 'tmp'
@@ -224,31 +217,6 @@ class AsciiDoc:
             except FileExistsError:
                 pass
 
-    def _get_asciidoc_cmd(self) -> List[str]:
-        """Try to find out what commandline to use to invoke asciidoc."""
-        if self._asciidoc is not None:
-            python = (sys.executable if self._asciidoc_python is None
-                      else self._asciidoc_python)
-            return [python, self._asciidoc]
-
-        for executable in ['asciidoc', 'asciidoc.py']:
-            try:
-                subprocess.run([executable, '--version'],
-                               capture_output=True,
-                               text=True,
-                               check=True)
-            except FileNotFoundError:
-                pass
-            except OSError as e:
-                utils.print_error(f"While running {executable}: {e}")
-            except subprocess.CalledProcessError as e:
-                utils.print_error(
-                    f"While running {executable}: {e}\n{e.stdout}\n{e.stderr}")
-            else:
-                return [executable]
-
-        raise FileNotFoundError
-
     def call(self, src: pathlib.Path, dst: pathlib.Path, *args):
         """Call asciidoc for the given files.
 
@@ -258,8 +226,7 @@ class AsciiDoc:
             *args: Additional arguments passed to asciidoc.
         """
         print("Calling asciidoc for {}...".format(src.name))
-        assert self._cmd is not None    # for mypy
-        cmdline = self._cmd[:]
+        cmdline = [sys.executable, "-m", "asciidoc"]
         if dst is not None:
             cmdline += ['--out-file', str(dst)]
         cmdline += args
@@ -286,12 +253,6 @@ def parse_args() -> argparse.Namespace:
     parser = argparse.ArgumentParser()
     parser.add_argument('--website', help="Build website into a given "
                         "directory.")
-    parser.add_argument('--asciidoc', help="Full path to asciidoc.py. "
-                        "If not given, it's searched in PATH.",
-                        nargs='?')
-    parser.add_argument('--asciidoc-python', help="Python to use for asciidoc."
-                        "If not given, the current Python interpreter is used.",
-                        nargs='?')
     return parser.parse_args()
 
 
@@ -303,9 +264,8 @@ def run(**kwargs) -> None:
     try:
         asciidoc.prepare()
     except FileNotFoundError:
-        utils.print_error("Could not find asciidoc! Please install it, or use "
-                          "the --asciidoc argument to point this script to "
-                          "the correct asciidoc.py location!")
+        utils.print_error("Could not find asciidoc! Please install it, e.g. via "
+                          "pip install -r misc/requirements/requirements-docs.txt")
         sys.exit(1)
 
     try:
@@ -319,8 +279,7 @@ def main(colors: bool = False) -> None:
     utils.change_cwd()
     utils.use_color = colors
     args = parse_args()
-    run(asciidoc=args.asciidoc, asciidoc_python=args.asciidoc_python,
-        website=args.website)
+    run(website=args.website)
 
 
 if __name__ == '__main__':
diff --git a/scripts/dev/build_release.py b/scripts/dev/build_release.py
index c175c68a7..20eb19e18 100755
--- a/scripts/dev/build_release.py
+++ b/scripts/dev/build_release.py
@@ -96,15 +96,10 @@ def call_tox(
         env=env, check=True)
 
 
-def run_asciidoc2html(args: argparse.Namespace) -> None:
+def run_asciidoc2html() -> None:
     """Run the asciidoc2html script."""
     utils.print_title("Running asciidoc2html.py")
-    a2h_args = []
-    if args.asciidoc is not None:
-        a2h_args += ['--asciidoc', args.asciidoc]
-    if args.asciidoc_python is not None:
-        a2h_args += ['--asciidoc-python', args.asciidoc_python]
-    call_script('asciidoc2html.py', *a2h_args)
+    call_script('asciidoc2html.py')
 
 
 def _maybe_remove(path: pathlib.Path) -> None:
@@ -684,12 +679,6 @@ def main() -> None:
     parser = argparse.ArgumentParser()
     parser.add_argument('--skip-docs', action='store_true',
                         help="Don't generate docs")
-    parser.add_argument('--asciidoc', help="Full path to asciidoc.py. "
-                        "If not given, it's searched in PATH.",
-                        nargs='?')
-    parser.add_argument('--asciidoc-python', help="Python to use for asciidoc."
-                        "If not given, the current Python interpreter is used.",
-                        nargs='?')
     parser.add_argument('--gh-token', help="GitHub token to use.",
                         nargs='?')
     parser.add_argument('--upload', action='store_true', required=False,
@@ -724,7 +713,7 @@ def main() -> None:
     if args.skip_docs:
         pathlib.Path("qutebrowser", "html", "doc").mkdir(parents=True, exist_ok=True)
     else:
-        run_asciidoc2html(args)
+        run_asciidoc2html()
 
     if os.name == 'nt':
         artifacts = build_windows(
diff --git a/scripts/dev/update_version.py b/scripts/dev/update_version.py
index 975787415..67e22ea26 100644
--- a/scripts/dev/update_version.py
+++ b/scripts/dev/update_version.py
@@ -81,8 +81,7 @@ if __name__ == "__main__":
           "tox -e build-release -- --upload"
           .format(v=version))
     print("* Windows: git fetch; git checkout v{v}; "
-          "py -3.9 -m tox -e build-release -- --asciidoc "
-          "$env:userprofile\\bin\\asciidoc-9.1.0\\asciidoc.py --upload"
+          "py -3.9 -m tox -e build-release -- --upload"
           .format(v=version))
     print("* macOS: git fetch && git checkout v{v} && "
           "tox -e build-release -- --upload"
diff --git a/scripts/mkvenv.py b/scripts/mkvenv.py
index 005c657a1..6b37bc9cb 100755
--- a/scripts/mkvenv.py
+++ b/scripts/mkvenv.py
@@ -81,9 +81,6 @@ def parse_args(argv: List[str] = None) -> argparse.Namespace:
     parser.add_argument('--virtualenv',
                         action='store_true',
                         help="Use virtualenv instead of venv.")
-    parser.add_argument('--asciidoc', help="Full path to asciidoc.py. "
-                        "If not given, asciidoc is searched in PATH.",
-                        nargs='?',)
     parser.add_argument('--dev',
                         action='store_true',
                         help="Also install dev/test dependencies.")
@@ -424,17 +421,14 @@ def install_qutebrowser(venv_dir: pathlib.Path) -> None:
     pip_install(venv_dir, '-e', str(REPO_ROOT))
 
 
-def regenerate_docs(venv_dir: pathlib.Path, asciidoc: Optional[str]):
+def regenerate_docs(venv_dir: pathlib.Path):
     """Regenerate docs using asciidoc."""
     utils.print_title("Generating documentation")
-    if asciidoc is not None:
-        a2h_args = ['--asciidoc', asciidoc]
-    else:
-        a2h_args = []
-    script_path = pathlib.Path(__file__).parent / 'asciidoc2html.py'
+    pip_install(venv_dir, '-r', str(requirements_file('docs')))
 
-    print_command('python3 scripts/asciidoc2html.py', *a2h_args, venv=True)
-    run_venv(venv_dir, 'python', str(script_path), *a2h_args)
+    script_path = pathlib.Path(__file__).parent / 'asciidoc2html.py'
+    print_command('python3 scripts/asciidoc2html.py', venv=True)
+    run_venv(venv_dir, 'python', str(script_path))
 
 
 def update_repo():
@@ -499,7 +493,7 @@ def run(args) -> None:
         install_dev_requirements(venv_dir)
 
     if not args.skip_docs:
-        regenerate_docs(venv_dir, args.asciidoc)
+        regenerate_docs(venv_dir)
 
 
 def main():