docs: update Sphinx version

Update the version for Sphinx. This includes:

- Switching to the latest release of Sphinx: v4.5.0

- Upgrading a few related dependencies (docutils, sphinx-tabs,
  sphinxcontrib-httpdomain)

- Updating some deprecated APIs:
      - app.add_javascript() -> app.add_js_file(),
      - app.stylesheet() -> app.add_css_file()

- Switching to a new parser for Markdown. MyST is now the recommended
  way to include Markdown files [0]. As a consequence, we drop the
  dependency for the former parser, recommonmark. Add suppression of
  some related warnings.

- Update the script for running spellchecks. The spellchecking extension
  has changed the way it reports mistakes, using a global warning to
  tell how many mistakes were found, and writing the reports to several
  files, one per source file containing mistakes. This makes it harder
  to retrieve the list of mistakes from console output, as we can no
  longer dissociate them from other warnings. Let's instead process the
  various files containing the reports. Since we touch the script,
  remove filtering expressions which do not seem to catch any existing
  warning.

Notes:

- Sphinx 4.5.0 does not recognise interpreted text as glossary terms, as
  older versions would do. But all glossary terms have been marked as
  such in a previous commit.

- MyST needs the path to the source Markdown files for creating links
  (not the generated HTML); The files generated for cmdref have all been
  updated accordingly in a previous commit.

- Docutils cannot be updated to the latest version: there is at least
  MyST which is not compatible with version 0.18.x [1].

[0] https://www.sphinx-doc.org/en/master/usage/markdown.html
[1] executablebooks/MyST-Parser#544

Signed-off-by: Quentin Monnet <quentin@isovalent.com>

Documentation/check-build.sh

@@ -12,7 +12,7 @@ script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
 build_dir="${script_dir}/_build"
 warnings="${build_dir}/warnings.txt"
-spelling="${build_dir}/spelling/output.txt"
+spelldir="${build_dir}/spelling"
 
 target="${1:-"html"}"
 shift
@@ -21,33 +21,26 @@ cd "${script_dir}"
 mkdir -p "${build_dir}"
 
 build_with_spellchecker() {
-    sphinx-build -b spelling -d "${build_dir}/doctrees" . "${build_dir}/spelling" -q -E 2> "${warnings}"
+    rm -rf "${spelldir}"
+    sphinx-build -b spelling -d "${build_dir}/doctrees" . "${spelldir}" -q -E 2> "${warnings}"
 }
 
 build_with_linkchecker() {
-    sphinx-build -b linkcheck -d "${build_dir}/doctrees" . "${build_dir}/spelling" -q -E
-}
-
-filter_warnings() {
-    grep -v \
-        -e "tabs assets" \
-        -e "misspelled words" \
-        -e "RemovedInSphinx20Warning" \
-        "${warnings}"
+    sphinx-build -b linkcheck -d "${build_dir}/doctrees" . "${spelldir}" -q -E
 }
 
 has_spelling_errors() {
-    test "$(wc -l < "${spelling}")" -ne 0 
+    test -n "$(ls "${spelldir}")"
 }
 
 describe_spelling_errors() {
     printf "\nPlease fix the following spelling mistakes:\n"
     # show file paths relative to repo root
-    sed 's/^/* Documentation\//' "${spelling}"
+    sed 's/^/* Documentation\//' "${spelldir}"/*
 }
 
 hint_about_wordlist_update() {
-    new_words="$(sed -E 's/^([^:]+:){2} \((.*)\)/\2/g' "${spelling}" | sort -u | tr -d '\r\n' | sed "s/'/\\\\\\\\'/g")"
+    new_words="$(sed -E "s/^([^:]+:){2} \(([^ ]+)\).*/\2/g" "${spelldir}"/* | sort -u | tr '\r\n' ' ' | sed "s/'/\\\\\\\\'/g")"
     printf "\nIf the words are not misspelled, run:\n%s %s\n" \
         "Documentation/update-spelling_wordlist.sh" "${new_words}"
 }
@@ -76,9 +69,9 @@ else
   echo "Validating documentation (syntax, spelling)..."
   if build_with_spellchecker ; then
     status_ok=0
-    if filter_warnings > /dev/null ;  then
+    if [ -s ${warnings} ]; then
         printf "\nPlease fix the following documentation warnings:\n"
-        filter_warnings
+        cat ${warnings}
         status_ok=1
     fi
 

Documentation/conf.py

@@ -36,7 +36,8 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 html_logo = "images/logo.svg"
-extensions = ['sphinx.ext.ifconfig',
+extensions = ['myst_parser',
+              'sphinx.ext.ifconfig',
               'sphinx.ext.githubpages',
               'sphinx.ext.extlinks',
               'sphinxcontrib.openapi',
@@ -52,9 +53,6 @@
 #
 # source_suffix = ['.rst', '.md']
 source_suffix = ['.rst', '.md']
-source_parsers = {
-    '.md': 'recommonmark.parser.CommonMarkParser',
-}
 
 # The master toctree document.
 master_doc = 'index'
@@ -159,6 +157,9 @@
 # Add custom filters for spell checks.
 spelling_filters = [cilium_spellfilters.WireGuardFilter]
 
+# Ignore some warnings from MyST parser
+suppress_warnings = ['myst.header']
+
 
 # -- Options for HTML output ----------------------------------------------
 
@@ -251,9 +252,9 @@
 
 
 def setup(app):
-    app.add_stylesheet('parsed-literal.css')
-    app.add_stylesheet('copybutton.css')
-    app.add_stylesheet('editbutton.css')
-    app.add_javascript('clipboardjs.min.js')
-    app.add_javascript("copybutton.js")
-    app.add_stylesheet('helm-reference.css')
+    app.add_css_file('parsed-literal.css')
+    app.add_css_file('copybutton.css')
+    app.add_css_file('editbutton.css')
+    app.add_js_file('clipboardjs.min.js')
+    app.add_js_file("copybutton.js")
+    app.add_css_file('helm-reference.css')

Documentation/requirements.txt

@@ -2,31 +2,31 @@ alabaster==0.7.12
 Babel==2.9.1
 certifi==2018.10.15
 chardet==3.0.4
-docutils==0.14
+docutils==0.17
 idna==2.7
 imagesize==1.1.0
 Jinja2==2.11.3
 jsonschema==2.6.0
 MarkupSafe==1.1.1
+myst-parser==0.17.0
 pyenchant==2.0.0
 Pygments==2.7.4
 pytz==2018.7
 PyYAML==5.4
-recommonmark==0.4.0
 requests==2.25.1
 semver==2.9.0
 six==1.15.0
 snowballstemmer==1.2.1
-Sphinx==1.8.1
+Sphinx==4.5.0
 sphinx-autobuild==0.7.1
 # forked read the docs themez
 git+https://github.com/cilium/sphinx_rtd_theme.git@v0.7; platform_machine != "aarch64"
 sphinx-rtd-theme==0.2.4; platform_machine == "aarch64"
-sphinxcontrib-httpdomain==1.7.0
+sphinxcontrib-httpdomain==1.8.0
 sphinxcontrib-openapi==0.3.2
 sphinxcontrib-spelling==4.2.1
 sphinxcontrib-websupport==1.1.0
-sphinx-tabs==1.1.13
+sphinx-tabs==3.3.1
 sphinx-version-warning==1.1.2
 typing==3.6.6
 urllib3==1.26.5