doc: Broken Python setup fixed by pinning dependencies

doc-kurento/requirements.txt

@@ -2,22 +2,31 @@
 # https://pip.pypa.io/en/latest/user_guide/#requirements-files
 #
 # Usage:
-#     # Create and load the Python virtual environment
+#     # Create and load a Python virtual environment.
 #     python3 -m venv python_modules
 #     source python_modules/bin/activate
 #
-#     # Install packages
+#     # Install packages.
+#     python3 -m pip install --upgrade wheel
 #     python3 -m pip install --upgrade -r requirements.txt
 
 Sphinx==4.5.0
 sphinx-rtd-theme==1.0.0
 
+# Need to pin exact dependencies of `Sphinx==4.5.0`, to avoid future breakages.
+# E.g. `sphinxcontrib-applehelp` started requiring Python 3.9 and Sphinx 5.0.
+sphinxcontrib-applehelp<=1.0.4
+sphinxcontrib-devhelp<=1.0.2
+sphinxcontrib-jsmath<=1.0.1
+sphinxcontrib-htmlhelp<=2.0.1
+sphinxcontrib-serializinghtml<=1.1.5
+sphinxcontrib-qthelp<=1.0.3
+
 # Sphinx extension "sphinxcontrib.video"
 # https://github.com/sphinx-contrib/video
 #sphinxcontrib-video==0.0.1.dev3
 # However, the extension is unmaintained and lacks some features, such as
 # support for Latex (that we use to generate PDF).
 # A fork exists here with needed fixes:
 # https://github.com/DavidPowell/video
-wheel
 git+https://github.com/DavidPowell/video.git@681dc0c522a66358428fcda83034fac054c37057

doc-kurento/source/dev/release.rst

@@ -814,12 +814,16 @@ For this reason, the documentation must be built only after all the other module
 
    .. code-block:: shell
 
+      # Create and load a Python virtual environment.
       python3 -m venv python_modules
       source python_modules/bin/activate
+
+      # Install packages.
+      python3 -m pip install --upgrade wheel
       python3 -m pip install --upgrade -r requirements.txt
-      make html
 
-   Repeat the *pip install* command if it fails. Python package management is so abysmally bad that this usually solves the issue.
+      # Build docs.
+      make html
 
    JavaDoc and JsDoc pages can be generated separately with ``make langdoc``.
 

doc-kurento/source/dev/writing_documentation.rst

@@ -67,15 +67,16 @@ Optionally, make a bit of cleanup in case old Sphinx versions were installed:
 
    python3 -m pip freeze | grep -i '^sphinx' | xargs sudo -H python3 -m pip uninstall
 
-And finally, install Sphinx:
+Finally, install and run Sphinx:
 
 .. code-block:: shell
 
-   # Create and load the Python virtual environment
+   # Create and load a Python virtual environment.
    python3 -m venv python_modules
    source python_modules/bin/activate
 
-   # Install Sphinx and the Read the Docs theme
+   # Install packages.
+   python3 -m pip install --upgrade wheel
    python3 -m pip install --upgrade -r requirements.txt
 
 
@@ -87,10 +88,10 @@ Run ``make html`` inside the documentation directory, and open the newly built f
 
 .. code-block:: shell
 
-   # Load the Python virtual environment
+   # Load the Python virtual environment.
    source python_modules/bin/activate
 
-   # Build and open the documentation files
+   # Build and open the documentation files.
    make html
    firefox build/html/index.html