Skip to content

[Doc]: Build failures on CircleCI #31019

New issue
New issue
Closed
Closed
[Doc]: Build failures on CircleCI#31019
Labels
Documentation

Description

@QuLogic
QuLogic
opened on Jan 23, 2026

Documentation Link

No response

Problem

Since a few days ago, docs have been failing to build on CircleCI with:

/home/circleci/project/doc/:1:<autosummary>:1: WARNING: py:obj reference target not found: matplotlib.animation.FFMpegFileWriter.frame_format [ref.obj]
/home/circleci/project/doc/:1:<autosummary>:1: WARNING: py:obj reference target not found: matplotlib.animation.FFMpegFileWriter.frame_size [ref.obj]
/home/circleci/project/doc/:1:<autosummary>:1: WARNING: py:obj reference target not found: matplotlib.animation.FFMpegFileWriter.output_args [ref.obj]
/home/circleci/project/doc/:1:<autosummary>:1: WARNING: py:obj reference target not found: matplotlib.animation.FileMovieWriter.frame_size [ref.obj]
/home/circleci/project/doc/:1:<autosummary>:1: WARNING: py:obj reference target not found: matplotlib.animation.FileMovieWriter.supported_formats [ref.obj]
/home/circleci/project/doc/:1:<autosummary>:1: WARNING: py:obj reference target not found: matplotlib.animation.FuncAnimation.pause [ref.obj]
/home/circleci/project/doc/:1:<autosummary>:1: WARNING: py:obj reference target not found: matplotlib.animation.FuncAnimation.resume [ref.obj]
/home/circleci/project/doc/:1:<autosummary>:1: WARNING: py:obj reference target not found: matplotlib.animation.FuncAnimation.save [ref.obj]
/home/circleci/project/doc/:1:<autosummary>:1: WARNING: py:obj reference target not found: matplotlib.animation.FuncAnimation.to_html5_video [ref.obj]
/home/circleci/project/doc/:1:<autosummary>:1: WARNING: py:obj reference target not found: matplotlib.animation.FuncAnimation.to_jshtml [ref.obj]
/home/circleci/project/doc/:1:<autosummary>:1: WARNING: py:obj reference target not found: matplotlib.animation.HTMLWriter.frame_format [ref.obj]
/home/circleci/project/doc/:1:<autosummary>:1: WARNING: py:obj reference target not found: matplotlib.animation.HTMLWriter.frame_size [ref.obj]
/home/circleci/project/doc/:1:<autosummary>:1: WARNING: py:obj reference target not found: matplotlib.animation.ImageMagickFileWriter.frame_format [ref.obj]
/home/circleci/project/doc/:1:<autosummary>:1: WARNING: py:obj reference target not found: matplotlib.animation.ImageMagickFileWriter.frame_size [ref.obj]
/home/circleci/project/doc/:1:<autosummary>:1: WARNING: py:obj reference target not found: matplotlib.animation.ImageMagickWriter.frame_size [ref.obj]
/home/circleci/project/doc/:1:<autosummary>:1: WARNING: py:obj reference target not found: matplotlib.animation.ImageMagickWriter.supported_formats [ref.obj]
/home/circleci/project/doc/:1:<autosummary>:1: WARNING: py:obj reference target not found: matplotlib.animation.MovieWriter.frame_size [ref.obj]
/home/circleci/project/doc/:1:<autosummary>:1: WARNING: py:obj reference target not found: matplotlib.animation.PillowWriter.frame_size [ref.obj]
<unknown>:4: WARNING: py:class reference target not found: matplotlib.patches._Style [ref.class]
<unknown>:4: WARNING: py:class reference target not found: matplotlib.patches.ArrowStyle._Curve [ref.class]
<unknown>:4: WARNING: py:class reference target not found: matplotlib.patches.ArrowStyle._Curve [ref.class]
<unknown>:4: WARNING: py:class reference target not found: matplotlib.patches.ArrowStyle._Curve [ref.class]
<unknown>:4: WARNING: py:class reference target not found: matplotlib.patches.ArrowStyle._Curve [ref.class]
<unknown>:4: WARNING: py:class reference target not found: matplotlib.patches.ArrowStyle._Curve [ref.class]
<unknown>:4: WARNING: py:class reference target not found: matplotlib.patches.ArrowStyle._Curve [ref.class]
<unknown>:4: WARNING: py:class reference target not found: matplotlib.patches.ArrowStyle._Curve [ref.class]
<unknown>:4: WARNING: py:class reference target not found: matplotlib.patches.ArrowStyle._Curve [ref.class]
<unknown>:4: WARNING: py:class reference target not found: matplotlib.patches.ArrowStyle._Curve [ref.class]
<unknown>:4: WARNING: py:class reference target not found: matplotlib.patches.ArrowStyle._Curve [ref.class]
<unknown>:4: WARNING: py:class reference target not found: matplotlib.patches.ArrowStyle._Curve [ref.class]
<unknown>:4: WARNING: py:class reference target not found: matplotlib.patches.ArrowStyle._Curve [ref.class]
<unknown>:4: WARNING: py:class reference target not found: matplotlib.patches.ArrowStyle._Curve [ref.class]
<unknown>:4: WARNING: py:class reference target not found: matplotlib.patches.ArrowStyle._Base [ref.class]
<unknown>:4: WARNING: py:class reference target not found: matplotlib.patches.ArrowStyle._Base [ref.class]
<unknown>:4: WARNING: py:class reference target not found: matplotlib.patches.ArrowStyle._Base [ref.class]
<unknown>:4: WARNING: py:class reference target not found: matplotlib.patches._Style [ref.class]
<unknown>:4: WARNING: py:class reference target not found: matplotlib.patches._Style [ref.class]
<unknown>:4: WARNING: py:class reference target not found: matplotlib.patches.ConnectionStyle._Base [ref.class]
<unknown>:4: WARNING: py:class reference target not found: matplotlib.patches.ConnectionStyle._Base [ref.class]
<unknown>:4: WARNING: py:class reference target not found: matplotlib.patches.ConnectionStyle._Base [ref.class]
<unknown>:4: WARNING: py:class reference target not found: matplotlib.patches.ConnectionStyle._Base [ref.class]
<unknown>:4: WARNING: py:class reference target not found: matplotlib.patches.ConnectionStyle._Base [ref.class]
<unknown>:4: WARNING: py:class reference target not found: mpl_toolkits.axes_grid1.axes_size._Base [ref.class]
<unknown>:4: WARNING: py:class reference target not found: mpl_toolkits.axes_grid1.axes_size._Base [ref.class]
<unknown>:4: WARNING: py:class reference target not found: mpl_toolkits.axes_grid1.axes_size._Base [ref.class]
<unknown>:4: WARNING: py:class reference target not found: mpl_toolkits.axes_grid1.axes_size._Base [ref.class]
<unknown>:4: WARNING: py:class reference target not found: mpl_toolkits.axes_grid1.axes_size._Base [ref.class]
<unknown>:4: WARNING: py:class reference target not found: mpl_toolkits.axes_grid1.axes_size._Base [ref.class]
<unknown>:4: WARNING: py:class reference target not found: mpl_toolkits.axes_grid1.axes_size._Base [ref.class]
<unknown>:4: WARNING: py:class reference target not found: matplotlib.patches._Style [ref.class]
<unknown>:4: WARNING: py:class reference target not found: mpl_toolkits.axisartist.axisline_style.AxislineStyle._Base [ref.class]
<unknown>:4: WARNING: py:class reference target not found: mpl_toolkits.axisartist.axislines._FixedAxisArtistHelperBase [ref.class]
<unknown>:4: WARNING: py:class reference target not found: mpl_toolkits.axisartist.axislines._FloatingAxisArtistHelperBase [ref.class]
<unknown>:4: WARNING: py:class reference target not found: mpl_toolkits.axisartist.axislines._FixedAxisArtistHelperBase [ref.class]
<unknown>:4: WARNING: py:class reference target not found: mpl_toolkits.axisartist.axislines._FloatingAxisArtistHelperBase [ref.class]
<unknown>:4: WARNING: py:class reference target not found: matplotlib.backend_bases._Backend [ref.class]
<unknown>:4: WARNING: py:class reference target not found: matplotlib.backends._backend_pdf_ps.RendererPDFPSBase [ref.class]
<unknown>:4: WARNING: py:class reference target not found: matplotlib.backends._backend_pdf_ps.RendererPDFPSBase [ref.class]
<unknown>:4: WARNING: py:class reference target not found: matplotlib.backends._backend_tk.FigureCanvasTk [ref.class]
<unknown>:4: WARNING: py:class reference target not found: matplotlib.backends._backend_tk.FigureCanvasTk [ref.class]
<unknown>:1: WARNING: py:class reference target not found: <class 'matplotlib.backend_tools.ToolCopyToClipboardBase'> [ref.class]
<unknown>:1: WARNING: py:class reference target not found: <class 'matplotlib.backend_tools.ToolSetCursor'> [ref.class]
<unknown>:1: WARNING: py:class reference target not found: <class 'matplotlib.backend_tools.ToolForward'> [ref.class]
<unknown>:1: WARNING: py:class reference target not found: <class 'matplotlib.backend_tools.ToolFullScreen'> [ref.class]
<unknown>:1: WARNING: py:class reference target not found: <class 'matplotlib.backend_tools.ToolGrid'> [ref.class]
<unknown>:1: WARNING: py:class reference target not found: <class 'matplotlib.backend_tools.ToolMinorGrid'> [ref.class]
<unknown>:1: WARNING: py:class reference target not found: <class 'matplotlib.backend_tools.ToolHelpBase'> [ref.class]
<unknown>:1: WARNING: py:class reference target not found: <class 'matplotlib.backend_tools.ToolHome'> [ref.class]
<unknown>:1: WARNING: py:class reference target not found: <class 'matplotlib.backend_tools.ToolPan'> [ref.class]
<unknown>:1: WARNING: py:class reference target not found: <class 'matplotlib.backend_tools.ToolCursorPosition'> [ref.class]
<unknown>:1: WARNING: py:class reference target not found: <class 'matplotlib.backend_tools.ToolQuit'> [ref.class]
<unknown>:1: WARNING: py:class reference target not found: <class 'matplotlib.backend_tools.ToolQuitAll'> [ref.class]
<unknown>:1: WARNING: py:class reference target not found: <class 'matplotlib.backend_tools.RubberbandBase'> [ref.class]
<unknown>:1: WARNING: py:class reference target not found: <class 'matplotlib.backend_tools.SaveFigureBase'> [ref.class]
<unknown>:1: WARNING: py:class reference target not found: <class 'matplotlib.backend_tools.ConfigureSubplotsBase'> [ref.class]
<unknown>:1: WARNING: py:class reference target not found: <class 'matplotlib.backend_tools.ToolViewsPositions'> [ref.class]
<unknown>:1: WARNING: py:class reference target not found: <class 'matplotlib.backend_tools.ToolXScale'> [ref.class]
<unknown>:1: WARNING: py:class reference target not found: <class 'matplotlib.backend_tools.ToolYScale'> [ref.class]
<unknown>:1: WARNING: py:class reference target not found: <class 'matplotlib.backend_tools.ToolZoom'>} [ref.class]
<unknown>:1: WARNING: py:class reference target not found: numpy.typing.NDArray [ref.class]
<unknown>:1: WARNING: py:class reference target not found: numpy.float64 [ref.class]
<unknown>:4: WARNING: py:class reference target not found: matplotlib.image._ImageBase [ref.class]
<unknown>:4: WARNING: py:class reference target not found: matplotlib.image._ImageBase [ref.class]
<unknown>:4: WARNING: py:class reference target not found: matplotlib.image._ImageBase [ref.class]
<unknown>:4: WARNING: py:class reference target not found: matplotlib.text._AnnotationBase [ref.class]
<unknown>:4: WARNING: py:class reference target not found: matplotlib.projections.geo._GeoTransform [ref.class]
<unknown>:4: WARNING: py:class reference target not found: matplotlib.projections.geo._GeoTransform [ref.class]
<unknown>:4: WARNING: py:class reference target not found: matplotlib.projections.geo._GeoTransform [ref.class]
<unknown>:4: WARNING: py:class reference target not found: matplotlib.projections.geo._GeoTransform [ref.class]
<unknown>:4: WARNING: py:class reference target not found: matplotlib.projections.geo._GeoTransform [ref.class]
<unknown>:4: WARNING: py:class reference target not found: matplotlib.projections.geo._GeoTransform [ref.class]
<unknown>:4: WARNING: py:class reference target not found: matplotlib.projections.geo._GeoTransform [ref.class]
<unknown>:4: WARNING: py:class reference target not found: matplotlib.projections.geo._GeoTransform [ref.class]
<unknown>:4: WARNING: py:class reference target not found: matplotlib.text._AnnotationBase [ref.class]
<unknown>:4: WARNING: py:class reference target not found: matplotlib.transforms._BlendedMixin [ref.class]
<unknown>:4: WARNING: py:class reference target not found: matplotlib.transforms._BlendedMixin [ref.class]

Seemingly, the difference between the last working and first failing build has been docutils 0.21.4->0.22.4, sphinx 8.2.3->9.1.0, and sphinx-design 0.6.1->0.7.0. Unfortunately, updating my venv to use these versions, I cannot reproduce the failures locally.

Looking at the warnings, there seems to be something wrong with parsing source locations, as there are many <unknown> or /home/circleci/project/doc/ (which seems to have been split or made relative incorrectly somehow?) but for items that should already be in the ignore file.

Suggested improvement

As I can't reproduce, it's difficult to come up with a fix. I've written up these notes in case someone else has some ideas.

Activity

  1. QuLogic
    added
    Documentation
    on Jan 23, 2026

  2. timhoffm commented on Jan 23, 2026

    @timhoffm
    timhoffm
    on Jan 23, 2026
    Member

    Sphinx 9 has a substantially rewritten autodoc, and there have been various issues with that. I suspect it's somehow related to that.

  3. QuLogic commented on Jan 23, 2026

    @QuLogic
    QuLogic
    on Jan 23, 2026
    MemberAuthor

    Ah, I just realized I've been testing without parallelism; adding O=-j4 does reproduce the warnings. It is indeed something from sphinx 9.

    Based on sphinx-doc/sphinx#14089, adding app.config.autodoc_use_legacy_class_based = True does fix several problems, leaving just the backend_tools classes as warning. For those, I believe it is trying to insert the types from the default value of the default_tools parameter to add_tools_to_manager.

  4. timhoffm commented on Jan 23, 2026

    @timhoffm
    timhoffm
    on Jan 23, 2026
    Member

    At least for some errors it seems that the warning message changed so that the entries in https://github.com/matplotlib/matplotlib/blob/main/doc/missing-references.json do not match anymore. To be checked whether updating missing-references.json is all that would need to be done.

  5. sanrishi commented on Jan 23, 2026

    @sanrishi
    sanrishi
    on Jan 23, 2026
    Contributor

    I see the docs-python3 failure, but it appears to be the Sphinx 9 regression. I noticed QuLogic opened #31020 to fix this, so I will wait for that to land before restarting the checks.

    My changes are verified locally with rstcheck and ready for review see #31016

  6. sachinu25 commented on Jan 27, 2026

    @sachinu25
    sachinu25
    on Jan 27, 2026 · Hidden as off-topic

  7. shivamrajsr07 commented on Mar 23, 2026

    @shivamrajsr07
    shivamrajsr07
    on Mar 23, 2026

    Hi, I would like to work on this issue.

    I will try to reproduce the documentation build failure locally using Sphinx 9 and investigate whether updating missing-references.json or adjusting the autodoc configuration resolves the warnings.

    If anyone has additional context or preferred direction, please let me know.

  8. timhoffm commented on May 17, 2026

    @timhoffm
    timhoffm
    on May 17, 2026
    Member

    Haven’t seen any problems either this lately.

  9. timhoffm
    closed this as completedon May 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Documentation

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions