Open ns-rse opened 1 month ago
Partial success.
Documentation is back online but only main
version works all others fail to be found (403) because whilst the main
branch builds in CI it fails for other branches.
I see the same error locally...
Extension error (sphinx_autodoc_typehints):
Handler <function process_docstring at 0x7d94184b4860> for event 'autodoc-process-docstring' threw an exception (exception: The frontend.OptionParser class will be replaced by a subclass of argparse.ArgumentParser in Docutils 0.21 or later.)
Traceback (most recent call last):
File "/home/neil/.virtualenvs/topostats/bin/sphinx-multiversion", line 8, in <module>
sys.exit(main())
^^^^^^
File "/home/neil/.virtualenvs/topostats/lib/python3.12/site-packages/sphinx_multiversion/main.py", line 338, in main
subprocess.check_call(cmd, cwd=current_cwd)
File "/usr/lib/python3.12/subprocess.py", line 413, in check_call
raise CalledProcessError(retcode, cmd)
subprocess.CalledProcessError: Command '('/home/neil/.virtualenvs/topostats/bin/python', '-R', '-m', 'sphinx', '-D', 'smv_metadata_path=/tmp/tmpiodbjbom/versions.json', '-D', 'smv_current_version=v2.0.0', '-c', '/home/neil/work/git/hub/AFM-SPM/TopoStats/docs', '/tmp/tmpiodbjbom/d819d1f3d0bed977cdfa926fb309a76a8e394462/docs', '/home/neil/work/git/hub/AFM-SPM/TopoStats/docs/_build/v2.0.0')' returned non-zero exit status 2.
This is because sphinx-autodoc-typehints uses OptionParser
imports docutils.frontend.OptionParser
which as noted will become deprecated in favour of argparse.ArgumentParser
subclass.
Why this happens on other versions I'm unsure, but I've opened an issue in sphinx-autodocs-typehints about this.
Currently the documentation fails to build.
Failed build
Current run is with Sphinx 7.3.7 fails with...
The installed packages and versions are listed in failed_packages.txt
Working build
An older run with Sphinx 7.2.6 built correctly.
The installed packages and versions are listed in
worked_packages.txt
Differences
Investigations
I can recreate the error locally in a fresh environment and its not and error with
sphinx-multiversion
as the same occurs when using theMakefile
to build a single version of the currently checked out commit.With
-P
/--pdb
Sphinx option enabled we see the following output pointing towardssphinx-autoapi
being the culprit (its the penultimate call in the traceback and callslist(doctree.traverse(toctree))
(NB this is not theautoapi
package at fault here).If we look at the source code in GitHub and check the blame we see this was corrected 2 months ago and is in the 3.1.0b0 pre-release and if we install the pre-release locally
make html
successfully builds the documentation :raised_hands: :tada:Unfortunately
sphinx-multiversion . _build
doesn't build all the version :crying_cat_face: one of the older versions (notmain
orv2.0.0
fails).Solution
Part 1
Temporarily peg the version of
sphinx-autoapi
inpyproject.toml
...and remember to remove this once
sphinx-autoapi-3.1.0
is released.Check and see what get built in GitHub Workflow.
Part 2
It may be desirable to restrict building of documentation to only tagged releases, there are some comments in
.github/workflows/sphinx_docs_to_gh_pages.yaml
on how to achieve this.