Docs build failure with Sphinx 8.2+ when using the dirhtml builder

XMLWordPrintableJSON

    • Type: Bug
    • Resolution: Fixed
    • Priority: Minor - P4
    • 2.0.3
    • Affects Version/s: None
    • Component/s: None
    • None
    • Not Needed
    • None
    • Fully Compatible
    • C Drivers
    • Not Needed
    • Hide

      1. What would you like to communicate to the user about this feature?
      2. Would you like the user to see examples of the syntax and/or executable code and its output?
      3. Which versions of the driver/connector does this apply to?

      Show
      1. What would you like to communicate to the user about this feature? 2. Would you like the user to see examples of the syntax and/or executable code and its output? 3. Which versions of the driver/connector does this apply to?
    • None
    • None
    • None
    • None
    • None
    • None

      Summary

      This is a minor build-time issue found by downstream packagers. When building docs with dirhtml, API changes in Sphinx 8.2 (October, 2024) cause the docs build to fail.

      Environment

      This does not occur if using a Poetry-installed version of Sphinx, because we have it pinned to 7.4. Installing Sphinx 8.2 or newer is required to reproduce. The issue only occurs in the dirhtml builder. The issue does not reproduce in EVG because it defaults to using the plain html builder.

      How to Reproduce

      Install Sphinx 8.2 or newer, and run the docs build with -b dirhtml. The build will fail in mongoc_common.py:generate_html_redirs

      Additional Background

      Downstream bug report: https://bugs.launchpad.net/ubuntu/+source/mongo-c-driver/+bug/2113467

      Breaking Sphinx commit: https://github.com/sphinx-doc/sphinx/commit/285908aa073e5320d5f5a8b4648a2265c76a3f32

      External PR: https://github.com/mongodb/mongo-c-driver/pull/2033

       

            Assignee:
            Colby Pike
            Reporter:
            Colby Pike
            Votes:
            0 Vote for this issue
            Watchers:
            1 Start watching this issue

              Created:
              Updated:
              Resolved: