Merge pull request #171 from bgilbert/sphinx

doc: fix Jekyll hiding a JS polyfill with Sphinx 5.x; drop support for Sphinx < 1.6

Author: bgilbert

doc/jekyll_fix.py

@@ -17,35 +17,34 @@
 # Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 #
 
-# Sphinx hardcodes that certain output directories have names starting with
+# Sphinx hardcodes that certain output paths have names starting with
 # an underscore.
 # Jekyll hardcodes that filenames starting with an underscore are not
 # deployed to the website.
-# Rename Sphinx output directories to drop the underscore.
+# Rename Sphinx output paths to drop the underscore.
 
 import os
 
+from sphinx.util import logging
 from sphinx.util.console import bold
 
 DIRS = {
     '_static': 'static',
     '_sources': 'sources',
 }
+FILES = {
+    # Added in Sphinx 5.0.0, scheduled to be removed in Sphinx 6
+    'static/_sphinx_javascript_frameworks_compat.js': 'static/sphinx_javascript_frameworks_compat.js',  # noqa: E501
+}
 REWRITE_EXTENSIONS = {'.html', '.js'}
 
 
-def remove_directory_underscores(app, exception):
+def remove_path_underscores(app, exception):
     if exception:
         return
     # Get logger
-    try:
-        from sphinx.util import logging
-
-        logger = logging.getLogger(__name__)
-    except (ImportError, AttributeError):
-        # Sphinx < 1.6
-        logger = app
-    logger.info(bold('fixing directory names... '), nonl=True)
+    logger = logging.getLogger(__name__)
+    logger.info(bold('fixing pathnames... '), nonl=True)
     # Rewrite references in HTML/JS files
     for dirpath, _, filenames in os.walk(app.outdir):
         for filename in filenames:
@@ -56,6 +55,8 @@ def remove_directory_underscores(app, exception):
                     contents = fh.read()
                 for old, new in DIRS.items():
                     contents = contents.replace(old + '/', new + '/')
+                for old, new in FILES.items():
+                    contents = contents.replace(old, new)
                 with open(path, 'w', encoding='utf-8') as fh:
                     fh.write(contents)
     # Move directory contents
@@ -70,8 +71,14 @@ def remove_directory_underscores(app, exception):
                 newfile = os.path.join(newdir, filename)
                 os.rename(oldfile, newfile)
             os.rmdir(olddir)
+    # Move files
+    for old, new in FILES.items():
+        oldfile = os.path.join(app.outdir, old)
+        newfile = os.path.join(app.outdir, new)
+        if os.path.isfile(oldfile):
+            os.rename(oldfile, newfile)
     logger.info('done')
 
 
 def setup(app):
-    app.connect('build-finished', remove_directory_underscores)
+    app.connect('build-finished', remove_path_underscores)