Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docfx build fails with "The sphinxcontrib.applehelp extension used by this project needs at least Sphinx v5.0" #344

Closed
parthea opened this issue Jan 13, 2024 · 3 comments
Assignees
Labels
priority: p1 Important issue which blocks shipping the next release. Will be fixed prior to next release. type: bug Error or flaw in code with unintended results or allowing sub-optimal usage patterns.

Comments

@parthea
Copy link
Contributor

parthea commented Jan 13, 2024

See build log here which shows the error reported in the title.

Releases of the sphinxcontrib-* dependencies were recently published which remove the requirement for sphinx>5:
sphinx-doc/sphinx#11567 (comment)

This library pins to sphinx==4.5.0

'sphinx==4.5.0',

Since the requirement for sphinx>5 was removed from the sphinxcontrib-* dependencies, we're pulling in the latest versions of sphinxcontrib-* instead of the ones that are compatible with sphinx 4.x

As a workaround, pinning to older versions of sphinxcontrib-* packages seems to allow the build pass

(py31013) partheniou@partheniou-vm-3:~/git/google-cloud-python/packages/google-cloud-securitycentermanagement$ git diff
diff --git a/packages/google-cloud-securitycentermanagement/noxfile.py b/packages/google-cloud-securitycentermanagement/noxfile.py
index 7d3551347c..6ab2bae199 100644
--- a/packages/google-cloud-securitycentermanagement/noxfile.py
+++ b/packages/google-cloud-securitycentermanagement/noxfile.py
@@ -308,6 +308,11 @@ def docfx(session):
 
     session.install("-e", ".")
     session.install(
+        "sphinxcontrib-applehelp==1.0.4",
+        "sphinxcontrib-devhelp==1.0.2",
+        "sphinxcontrib-htmlhelp==2.0.1",
+        "sphinxcontrib-qthelp==1.0.3",
+        "sphinxcontrib-serializinghtml==1.1.5",
         "gcp-sphinx-docfx-yaml",
         "alabaster",
         "recommonmark",

To see which versions are compatible with sphinx 4.x, see the changelogs here:
https://github.com/sphinx-doc/sphinxcontrib-applehelp/blob/master/CHANGES
https://github.com/sphinx-doc/sphinxcontrib-devhelp/blob/master/CHANGES
https://github.com/sphinx-doc/sphinxcontrib-htmlhelp/blob/master/CHANGES
https://github.com/sphinx-doc/sphinxcontrib-qthelp/blob/master/CHANGES
https://github.com/sphinx-doc/sphinxcontrib-serializinghtml/blob/master/CHANGES

Output from local run without the workaround:

(py31013) partheniou@partheniou-vm-3:~/git/google-cloud-python/packages/google-cloud-securitycentermanagement$ nox -s docfx
nox > Running session docfx
nox > Creating virtual environment (virtualenv) using python3.10 in .nox/docfx
nox > python -m pip install -e .
nox > python -m pip install gcp-sphinx-docfx-yaml alabaster recommonmark
nox > sphinx-build -T -N -D extensions=sphinx.ext.autodoc,sphinx.ext.autosummary,docfx_yaml.extension,sphinx.ext.intersphinx,sphinx.ext.coverage,sphinx.ext.napoleon,sphinx.ext.todo,sphinx.ext.viewcode,recommonmark -b html -d docs/_build/doctrees/ docs/ docs/_build/html/
Running Sphinx v4.5.0

Traceback (most recent call last):
  File "/usr/local/google/home/partheniou/git/google-cloud-python/packages/google-cloud-securitycentermanagement/.nox/docfx/lib/python3.10/site-packages/sphinx/registry.py", line 438, in load_extension
    metadata = setup(app)
  File "/usr/local/google/home/partheniou/git/google-cloud-python/packages/google-cloud-securitycentermanagement/.nox/docfx/lib/python3.10/site-packages/sphinxcontrib/applehelp/__init__.py", line 230, in setup
    app.require_sphinx('5.0')
  File "/usr/local/google/home/partheniou/git/google-cloud-python/packages/google-cloud-securitycentermanagement/.nox/docfx/lib/python3.10/site-packages/sphinx/application.py", line 393, in require_sphinx
    raise VersionRequirementError(version)
sphinx.errors.VersionRequirementError: 5.0

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/usr/local/google/home/partheniou/git/google-cloud-python/packages/google-cloud-securitycentermanagement/.nox/docfx/lib/python3.10/site-packages/sphinx/cmd/build.py", line 272, in build_main
    app = Sphinx(args.sourcedir, args.confdir, args.outputdir,
  File "/usr/local/google/home/partheniou/git/google-cloud-python/packages/google-cloud-securitycentermanagement/.nox/docfx/lib/python3.10/site-packages/sphinx/application.py", line 219, in __init__
    self.setup_extension(extension)
  File "/usr/local/google/home/partheniou/git/google-cloud-python/packages/google-cloud-securitycentermanagement/.nox/docfx/lib/python3.10/site-packages/sphinx/application.py", line 380, in setup_extension
    self.registry.load_extension(self, extname)
  File "/usr/local/google/home/partheniou/git/google-cloud-python/packages/google-cloud-securitycentermanagement/.nox/docfx/lib/python3.10/site-packages/sphinx/registry.py", line 441, in load_extension
    raise VersionRequirementError(
sphinx.errors.VersionRequirementError: The sphinxcontrib.applehelp extension used by this project needs at least Sphinx v5.0; it therefore cannot be built with this version.

Sphinx version error:
The sphinxcontrib.applehelp extension used by this project needs at least Sphinx v5.0; it therefore cannot be built with this version.
nox > Command sphinx-build -T -N -D extensions=sphinx.ext.autodoc,sphinx.ext.autosummary,docfx_yaml.extension,sphinx.ext.intersphinx,sphinx.ext.coverage,sphinx.ext.napoleon,sphinx.ext.todo,sphinx.ext.viewcode,recommonmark -b html -d docs/_build/doctrees/ docs/ docs/_build/html/ failed with exit code 2
nox > Session docfx failed.
@parthea parthea added type: bug Error or flaw in code with unintended results or allowing sub-optimal usage patterns. priority: p1 Important issue which blocks shipping the next release. Will be fixed prior to next release. labels Jan 13, 2024
@dandhlee dandhlee self-assigned this Jan 24, 2024
@dandhlee
Copy link
Collaborator

Will work on this ASAP - partners are running into this issue when they use the plugin directly and not through Kokoro jobs.

@Ark-kun
Copy link

Ark-kun commented Feb 29, 2024

@dandhlee
Copy link
Collaborator

Oped to disable the problematic golden tests to prioritize fixing this first instead. New release has been made, verified that changes work on older client libraries.

We could optionally remove the added installs in nox, but not a priority.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
priority: p1 Important issue which blocks shipping the next release. Will be fixed prior to next release. type: bug Error or flaw in code with unintended results or allowing sub-optimal usage patterns.
Projects
None yet
Development

No branches or pull requests

3 participants