Pin down python package versions and fix build errors

Sphinxsetup.bat

@@ -2,7 +2,7 @@ rem remove any existing packages that may cause conflicts
 pip uninstall -y sphinx lxml sphinx-rtd-theme sphinxcontrib-youtube beautifulsoup4
 
 rem Install sphinx
-pip install --upgrade sphinx
+pip install --upgrade sphinx==5.1.1 docutils==0.16
 
 rem lxml for parameter parsing:
 pip install --upgrade lxml
@@ -12,7 +12,6 @@ pip install --upgrade git+https://github.com/ArduPilot/sphinx_rtd_theme.git
 
 rem and a youtube plugin:
 pip install --upgrade git+https://github.com/ArduPilot/sphinxcontrib-youtube.git
-pip install --upgrade git+https://github.com/ArduPilot/sphinxcontrib.vimeo.git
 
 rem and a parser to use getting posts from Discourse (forum) and insert in FrontEnd
 pip install --upgrade beautifulsoup4

Sphinxsetup.sh

@@ -48,8 +48,11 @@ curl "$GET_PIP_URL" -o get-pip.py
 python3 get-pip.py
 rm -f get-pip.py
 
-# Install sphinx
-python3 -m pip install --user --upgrade sphinx
+# Install python packages using known working versions
+# Install sphinx with a specific docutils version
+# Docutils version is for correct bullet point rendering. Can be rolled forward after theme is updated to >=0.5.1
+# See https://stackoverflow.com/a/68685753/2578171
+python3 -m pip install --user --upgrade sphinx==5.1.1 docutils==0.16
 
 # lxml for parameter parsing:
 python3 -m pip install --user --upgrade lxml
@@ -58,8 +61,9 @@ python3 -m pip install --user --upgrade lxml
 python3 -m pip install --user --upgrade git+https://github.com/ArduPilot/sphinx_rtd_theme.git
 
 # and youtube and video plugins:
+# This command might require a --force option if you have and older extension installed
+# Rerun Sphinxsetup.sh after doing that
 python3 -m pip install --user --upgrade git+https://github.com/ArduPilot/sphinxcontrib-youtube.git
-python3 -m pip install --user --upgrade git+https://github.com/ArduPilot/sphinxcontrib.vimeo.git
 
 # and a parser to use getting posts from Discourse (forum) and insert in FrontEnd
 python3 -m pip install --user --upgrade beautifulsoup4

common_conf.py

@@ -3,9 +3,6 @@
 # This contains common configuration information for the ardupilot wikis.
 # This information is imported by the conf.py files in each of the sub wikis
 
-import warnings
-from packaging import version
-import pkg_resources
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
@@ -19,26 +16,6 @@
     'sphinxcontrib.youtube',  # For youtube embedding
 ]
 
-
-def custom_formatwarning(msg, *args, **kwargs):
-    # ignore everything except the message
-    return str(msg) + '\n'
-
-
-warnings.formatwarning = custom_formatwarning
-
-# Check if sphinxcontrib.youtube version is high enough to handle vimeo and older python versions
-if version.parse(pkg_resources.get_distribution('sphinxcontrib-youtube').version) < version.parse('1.0.1'):
-    warnings.warn('\033[93mModule sphinxcontrib-youtube is outdated. PDF documentation cannot be built. ' +
-                  'Please run "python3 -m pip install --upgrade sphinxcontrib-youtube"')
-    try:
-        # Check if sphinxcontrib.vimeo extension is present, fallback to using that to handle vimeo
-        import sphinxcontrib.vimeo  # noqa: F401
-        extensions.append('sphinxcontrib.vimeo')  # For vimeo embedding
-    except ImportError:  # change to ModuleNotFoundError when only python >=3.6 is supported
-        warnings.warn('\033[93mModule sphinxcontrib-youtube is old and sphinxcontrib-vimeo is not installed.' +
-                      'Please run the wiki build setup script.')
-
 # Set False to re-enable warnings for non-local images.
 disable_non_local_image_warnings = True
 

update.py

@@ -738,9 +738,8 @@ def copy_static_html_sites(site, destdir):
     """
     Copy pure HMTL folder the same way that Sphinx builds it
     """
-    debug('Copying static sites (only frontend so far).')
-
-    if (site == 'frontend') or (site is None):
+    if (site in ['frontend', None]) and (destdir is not None):
+        debug('Copying static sites (only frontend so far).')
         update_frotend_json()
         folder = 'frontend'
         try:
@@ -756,22 +755,15 @@ def copy_static_html_sites(site, destdir):
 def check_imports():
     '''check key imports work'''
     import pkg_resources
-    requires = ["sphinx_rtd_theme>=0.1.8", "sphinxcontrib.vimeo>=0.0.1"]
+    # package names to check the versions of. Note that these can be different than the string used to import the package
+    requires = ["sphinx_rtd_theme>=0.1.8", "sphinxcontrib.youtube>=1.2.0", "sphinx==5.1.1", "docutils==0.16"]
     for r in requires:
         print("Checking for %s" % r)
         try:
             pkg_resources.require(r)
         except pkg_resources.ResolutionError as ex:
             print(ex)
             fatal("Require %s" % r)
-    # special case for sphinxcontrib.youtube as it isn't setup properly as a package
-    try:
-        import sphinxcontrib.youtube
-        if pkg_resources.parse_version(sphinxcontrib.youtube.__version__) < pkg_resources.parse_version("1.2.0"):
-            fatal("sphinxcontrib.youtube too old %s < %s" % (sphinxcontrib.youtube.__version__, "1.2.0"))
-    except Exception as ex:
-        print(ex)
-        fatal("Failed to check sphinxcontrib.youtube version")
     print("Imports OK")
 
 
@@ -889,5 +881,7 @@ def check_imports():
     if error_count > 0:
         print("%u errors during Wiki build" % (error_count,))
         sys.exit(1)
+    else:
+        print("Build completed without errors")
 
     sys.exit(0)