[Docs] Update sphinx to 3.4

Version 3.4 was chosen for compatibility with Debian oldstable (11 at
the time of this writing).

Signed-off-by: Wojtek Porczyk <woju@invisiblethingslab.com>

Documentation/conf.py

@@ -126,7 +126,7 @@ def generate_doxygen(app):
             subprocess.check_call(['doxygen', 'Doxyfile-{}'.format(p)])
 
 def setup(app):
-    app.add_stylesheet('css/gramine.css')
+    app.add_css_file('css/gramine.css')
     app.connect('builder-inited', generate_doxygen)
 
 todo_include_todos = True

Documentation/devel/howto-doc.rst

@@ -42,9 +42,7 @@ Installing prerequisites
 ------------------------
 
 Change directory to ``Documentation``, install prerequisites including Doxygen,
-Breathe and Sphinx. Gramine documentation requires version 1.8 of Sphinx. The
-documentation is built with python3; if you have similar packages in python2, it
-may create problems; we recommend removing any similar packages in python2.
+Breathe and Sphinx. Gramine documentation requires version 3.4 of Sphinx.
 
 .. code-block:: sh
 

Documentation/requirements.txt

@@ -1,15 +1,25 @@
-sphinx==1.8.0
-breathe<4.13.0
+sphinx==3.4.*
 recommonmark==0.7.1
-sphinx_rtd_theme<1
+sphinx_rtd_theme
 tomli>=1.1.0
 
-# Work around Sphinx/docutils incompatibility, see https://github.com/sphinx-doc/sphinx/issues/9727.
-# TODO: This shouldn't be necessary once we upgrade to newer Sphinx (Sphinx 4.2.0 is not yet
-# compatible with new docutils, but pins the docutils version by itself).
-docutils<0.18
-
 # jinja 3.1.0 removed quite a few functions used by sphinx
+# TODO: remove this after sphinx>=4
 # https://jinja.palletsprojects.com/en/3.1.x/changes/#version-3-1-0
 # https://github.com/pallets/jinja/pull/1544
 jinja2<3.1
+
+# those require sphinx >= 5.0
+# https://github.com/sphinx-doc/sphinxcontrib-applehelp/commit/604e2cb89264b6e2669ac8c15a70d93c1e06d9d3
+sphinxcontrib-applehelp<1.0.5
+# https://github.com/sphinx-doc/sphinxcontrib-devhelp/commit/448fbf6ef773d1fcc9372baf6c8bd8ac27a0a337
+sphinxcontrib-devhelp<1.0.3
+# https://github.com/sphinx-doc/sphinxcontrib-htmlhelp/commit/5a4cbeee53b7bd65453b1847805e6432cfd34b3c
+sphinxcontrib-htmlhelp<2.0.2
+# https://github.com/sphinx-doc/sphinxcontrib-serializinghtml/commit/4ae674533ed62a2da64e7d69d5be50baa35bc16d
+sphinxcontrib-serializinghtml<1.1.6
+# https://github.com/sphinx-doc/sphinxcontrib-qthelp/commit/73d2bfb73e02c16ced9dd84310dc44dda8ef26ff
+sphinxcontrib-qthelp<1.0.4
+
+# https://github.com/breathe-doc/breathe/pull/469
+breathe>=4.26.0,<4.27

debian/control

@@ -16,9 +16,9 @@ Build-Depends: debhelper-compat (= 13),
  perl,
  pkg-config,
  protobuf-c-compiler,
- python3-breathe,
+ python3-breathe (>= 4.26),
  python3-recommonmark,
- python3-sphinx,
+ python3-sphinx (>= 3.4),
  python3-sphinx-rtd-theme,
  python3-tomli (>= 1.1.0),
  python3-tomli-w (>= 0.4.0),

gramine.spec

@@ -1,5 +1,12 @@
 # Copyright (c) 2021-2022 Wojtek Porczyk <woju@invisiblethingslab.com>
 
+# .el8 has sphinx 1.8 which is too old
+%if (! 0%{rhel}) || 0%{rhel} >= 9
+    %define has_supported_sphinx 1
+%else
+    %define has_supported_sphinx 0
+%endif
+
 Name: gramine
 Version: 1.6.1post~UNRELEASED
 Release: 1%{?dist}
@@ -24,9 +31,11 @@ BuildRequires: perl
 BuildRequires: protobuf-c-compiler
 BuildRequires: protobuf-c-devel
 BuildRequires: python3-devel
+%if %{has_supported_sphinx}
 BuildRequires: python3-recommonmark
-BuildRequires: python3-sphinx
+BuildRequires: python3-sphinx >= 3.4
 BuildRequires: python3-sphinx_rtd_theme
+%endif
 
 Requires: python3-click >= 6.7
 Requires: python3-cryptography
@@ -69,13 +78,17 @@ fi
 
 %meson_build
 
+%if %{has_supported_sphinx}
 %__make -C Documentation man
+%endif
 
 %install
 %meson_install
 
+%if %{has_supported_sphinx}
 install -d %{buildroot}/%{_mandir}/man1
 install -t %{buildroot}/%{_mandir}/man1 Documentation/_build/man/*.1
+%endif
 
 install -d %{buildroot}/%{_licensedir}/%{name}
 install -t %{buildroot}/%{_licensedir}/%{name} LICENSE*.txt
@@ -122,7 +135,9 @@ install -t %{buildroot}/%{_licensedir}/%{name} LICENSE*.txt
 %{_includedir}/gramine/mbedtls/*.h
 %{_includedir}/gramine/psa/*.h
 
+%if %{has_supported_sphinx}
 %{_mandir}/man1/%{name}-*.1*
 %{_mandir}/man1/is-sgx-available.1*
+%endif
 
 %doc %{_licensedir}/%{name}/LICENSE*.txt