sphinxcontrib-versioning: Build fails for release and forks, advice?

Hi Anton !

I encountered the same problem with the sphinxcontrib-versioning 2.2.1 from pypi. Even if I solved my problem in #66 I’m still stuck like you mentioned above.

I’ve been hit by this as well and tried to figure out what broke in which sphinx versions. I’ve used the Docker sphinx that I maintain for this and used the “quick-and-dirty” documentation from the tutorial for testing.

• for 1.6.5 to work, I had to apply #46
• for 1.7.0 to work, I had to apply #69 as well as the argv[1:] fix mentioned above in addition to #46
• for 1.8.0 to work, I had to apply #57 in addition to the changes for 1.7.0 and 1.6.5
• for 2.0.0 to work, I had to apply #57 in addition to the changes for 1.7.0 and 1.6.5

Version 2.0.1 is the first version where I observed the hang/freeze. Apart from the sphinx version, there are no other differences between my Docker images for 2.0.0 and 2.0.1. The changes between those two don’t provide any clue, to me at least, what might have triggered this.

It took me a while but I finally figured it out for good.

I will not make a PR because I find the fix to be especially ugly but I leave it there as a git patch for those encountering the issue.

The bug happens starting from Sphinx 2.0.1 as some noticed and is due to the fact that the CONFIG_FILENAME attribute of the sphinx.application module was deprecated with a 3.0.0 deletion in mind. Now the Sphinx deprecation helper actually wrap the entire module in sys.modules into a _ModuleWrapper to wrap the module __getattribute__ to send a DeprecationWarning if the deprecated attribute is to be fetch. This is all good and all but it does breaks the attempt that sphinxcontrib.versioning makes to monkey patch the sphinx.application.Config object to auto-register sphinxcontrib.versioning.sphinx_ as an extension (which actually fixes the hang as previous comments found out) upon instantiation.

My UGLY hotfix bypasses the _ModuleWrapper explicitly and will not work for sphinx versions before the 2.0.1 and after at least the 3.0.0.

Index: sphinxcontrib/versioning/sphinx_.py
<+>UTF-8
===================================================================
--- sphinxcontrib/versioning/sphinx_.py	(revision f286d43595d75c08cb51a0153a9cdf3b8a1957b3)
+++ sphinxcontrib/versioning/sphinx_.py	(date 1582638010030)
@@ -184,8 +184,13 @@
     :param str current_name: The ref name of the current version being built.
     :param bool is_root: Is this build in the web root?
     """
-    # Patch.
-    application.Config = ConfigInject
+    # Update monkey patch to work with Sphinx 2.0.1+ _ModuleWrapper addition around sphinx.application due to
+    # CONFIG_FILENAME deprecation.
+    # _ModuleWrapper does not redirect __setattr__ calls to the underlying module so we need to bypass it to inject
+    # the extension.
+    # This is ugly and will break starting from at least Sphinx 3.0+ but the idea of monkey patching the extension
+    # silently into sphinx was hackish at most to begin with.
+    application._module.Config = ConfigInject  # noqa
     if config.show_banner:
         EventHandlers.BANNER_GREATEST_TAG = config.banner_greatest_tag
         EventHandlers.BANNER_MAIN_VERSION = config.banner_main_ref

@GlitchyPSIX I’ve resorted to conditionally added the extension based on an environment variable. Since I normally only want to run sphinx-versionsing in CI (and sphinx-build during “development” of the documentation), I have added it like so

if 'CI' in os.environ and os.environ['CI'] == 'true':
    extensions.append('sphinxcontrib.versioning.sphinx_')

Works For Me 😄

I’m aware of your work around but that doesn’t solve thing for documentation versions that have already been committed and pushed 😢

@dlopezlo Yes (sphinx 2.2.1), I have managed to get sphinxcontrib-versioning building properly by applying #46, #66, and the argv[1:] fix (I did them in this order)

Do remember to add the sphinxcontrib.versioning.sphinx_ extension in conf.py

I made a separate conf.py for when I want to build separately without versioning which doesn’t have that extension which I build using sphinx-build

Hi there, after digging around for 1 hour, I found a simple hack should work for this case.

https://github.com/sphinx-contrib/sphinxcontrib-versioning/blob/86a28dc92ce3ff42ed36a8b3e4dc6bdcff90f2c4/sphinxcontrib/versioning/sphinx_.py#L202

Change the argv to argv[1:].

Currently by default argv has three elements: sphinx-build, {SOURCE}, {TARGET}. But I suspect the new sphinx accepts only the last two, it will treat {TARGET} as filename option and check if it’s really a file, which is a folder of course (Here’s the logging line Not files).