[docs] Update docuementation about webkitgtk and wpewebkit runners

This is a follow-up to commit c9da6f7 to fix some missing backticks
in the wpewebkit_minibrowser documentation.

Seize this to improve a bit the text of the documentation as well as
the rendered format.

Also update the documentation on how to build the docs locally that
was outdated since a7c2f53

docs/README.md

@@ -15,10 +15,10 @@ If you would like to build the site locally, follow these instructions.
    variety of systems.
 2. Download the source code. Clone this repository using the `git clone`
    command.
-3. Install the Python dependencies. Run the following command in a terminal
-   from the "docs" directory of the WPT repository:
+3. Install the Python dependencies. Run the following command in a terminal:
 
-       pip install -r requirements.txt
+       pip install -r docs/requirements.txt
 
-4. Build the documentation. Windows users should execute the `make.bat` batch
-   file. GNU/Linux and macOS users should use the `make` command.
+4. Build the documentation:
+
+       ./wpt build-docs

docs/running-tests/webkitgtk_minibrowser.md

@@ -27,10 +27,10 @@ This universal bundles should work on any Linux distribution as they include ins
 the tarball all the system libraries and resources needed to run WebKitGTK, from libc
 up to the Mesa graphics drivers without requiring the usage of containers.
 
-If you are not using open source graphics drivers (Mesa) and you experience issues
-with this bundle then a possible workaround is to try to run the tests headless
+If you are using proprietary graphics drivers (NVIDIA, AMDGPU PRO, etc) and you experience
+issues with this bundle then a possible workaround is to try to run the tests headless
 inside a virtualized display like `Xvfb` (see command `xvfb-run -a` on Debian/Ubuntu).
-You can do this also from inside a virtual machine or docker container.
+You can do this also from inside a virtual machine or Docker container.
 
 # Headless mode
 
@@ -40,28 +40,31 @@ by running the tests inside a virtualized display. For example you can use
 or you can use `Xvfb` for a virtualized `X11` display.
 
 Example:
-   ```
-   xvfb-run -a ./wpt run [more-options] webkitgtk_minibrowser [tests-to-run]
-   ```
+
+    xvfb-run -a ./wpt run [more-options] webkitgtk_minibrowser [tests-to-run]
+
 
 # Using a custom WebKitGTK build
 
 If you want to test with a custom WebKitGTK build the easiest way is that you
-install this build in a temporary directory and then tell wpt to run it from there.
+install this build in a temporary directory (`/tmp/wkgtktest` in this example),
+and then tell `wpt` to run it from there.
 
 Steps:
 
-  1. Build WebKitGTK passing the arguments `-DENABLE_MINIBROWSER=ON -DCMAKE_INSTALL_PREFIX=/home/user/testdir_install`
-  2. Install it: `ninja install` (or `make install`)
-  3. Locate the `MiniBrowser` and `WebKitWebDriver` binaries under `/home/user/testdir_install`
-  4. Run `wpt` passing this two paths like this:
-  ```
-      ./wpt run --webdriver-binary=/home/user/testdir_install/bin/WebKitWebDriver \
-                --binary=/home/user/testdir_install/libexec/MiniBrowser \
-                [more-options] webkitgtk_minibrowser [tests-to-run]
-  ```
-
- * Note: It is important that you build WebKitGTK against the libraries of your system.
+1. Build WebKitGTK passing these arguments to `CMake`:
+
+       -DENABLE_MINIBROWSER=ON -DCMAKE_INSTALL_PREFIX=/tmp/wkgtktest
+
+2. Install it: `ninja install` (or `make install`)
+3. Locate the `MiniBrowser` and `WebKitWebDriver` binaries under the install directory.
+4. Run `wpt` passing these two paths like this:
+
+       ./wpt run --webdriver-binary=/tmp/wkgtktest/bin/WebKitWebDriver \
+                 --binary=/tmp/wkgtktest/libexec/MiniBrowser \
+                 [more-options] webkitgtk_minibrowser [tests-to-run]
+
+Note: It is important that you build WebKitGTK against the libraries of your system.
 Do not build WebKitGTK inside Flatpak or other container unless you run `wpt` also
 from inside this container.
 

docs/running-tests/wpewebkit_minibrowser.md

@@ -23,39 +23,42 @@ default `wpt` working directory (usually subdir `_venv3/browsers` in your `wpt`
 Then it will use the unpacked `MiniBrowser` and `WPEWebDriver` binaries to run the tests.
 
 This universal bundles should work on any Linux distribution as they include inside
-the tarball all the system libraries and resources needed to run WebKitGTK, from libc
+the tarball all the system libraries and resources needed to run WPE WebKit, from libc
 up to the Mesa graphics drivers without requiring the usage of containers.
 
-If you are not using open source graphics drivers (Mesa) and you experience issues
-with this bundle then a possible workaround is to try to run the tests in headless
-mode, for that pass the flag `--headless` to `wpt`
+If you are using proprietary graphics drivers (NVIDIA, AMDGPU PRO, etc) and you experience
+issues with this bundle then a possible workaround is to try to run the tests in
+headless mode, for that pass the flag `--headless` to `wpt`
 
 # Headless mode
 
 The WPE MiniBrowser needs a Wayland display to run, but if you don't have one
 or you want to enable headless mode you can pass the flag `--headless` to `wpt`.
 
 Example:
-   ```
-   ./wpt run [more-options] --headless wpewebkit_minibrowser [tests-to-run]
-   ```
+```
+./wpt run [more-options] --headless wpewebkit_minibrowser [tests-to-run]
+```
 
 # Using a custom WPE WebKit build
 
 If you want to test with a custom WPE WebKit build the easiest way is that you
-install this build in a temporary directory and then tell wpt to run it from there.
+install this build in a temporary directory (`/tmp/wpetest` in this example),
+and then tell `wpt` to run it from there.
 
 Steps:
 
-  1. Build WPE WebKit passing the arguments `-DENABLE_MINIBROWSER=ON -DCMAKE_INSTALL_PREFIX=/home/user/testdir_install'
-  2. Install it: `ninja install` (or `make install`)
-  3. Locate the `MiniBrowser` and `WPEWebDriver` binaries under /home/user/testdir_install`
-  4. Run `wpt` passing this two paths like this:
-  ```
-      ./wpt run --webdriver-binary=/home/user/testdir_install/bin/WPEWebDriver \
-                --binary=/home/user/testdir_install/libexec/MiniBrowser \
-                [more-options] webkitgtk_minibrowser [tests-to-run]
-  ```
+1. Build WPE WebKit passing these arguments to `CMake`:
+
+       -DENABLE_MINIBROWSER=ON -DCMAKE_INSTALL_PREFIX=/tmp/wpetest
+
+2. Install it: `ninja install` (or `make install`)
+3. Locate the `MiniBrowser` and `WPEWebDriver` binaries under the install directory.
+4. Run `wpt` passing these two paths like this:
+
+       ./wpt run --webdriver-binary=/tmp/wpetest/bin/WPEWebDriver \
+                 --binary=/tmp/wpetest/libexec/MiniBrowser \
+                 [more-options] webkitgtk_minibrowser [tests-to-run]
 
 Note: It is important that you build WPE WebKit against the libraries of your system.
 Do not build WPE WebKit inside Flatpak or other container unless you run `wpt` also