autoapi options in pickled environment always marked as changed

[PProfizi]

🔍 Before submitting the issue

• I have searched among the existing issues
• I am using a Python virtual environment

🐞 Description of the bug

Hi,

I have been investigating how to accelerate doc build for pydpf-core using a cache of the build folder generated by Sphinx.
While trying to make this work I have built the doc locally quite a few times and consistently gotten the following message at the beginning of the build:

loading pickled environment... The configuration has changed (15 options: 'autoapi_dirs', 'autoapi_ignore', 'autoapi_keep_files', 'autoapi_options', 'autoapi_own_page_level', ...)

see for example here

I have now tried a lot of things to try and make Sphinx see that the configuration has in fact not changed.

The issue with this is that it tells Sphinx to regenerate everything as if the config had changed.

What I realized though is that these 15 options marked as changed every time I run are options managed by ansys-sphinx-theme's autoapi extension (such as here).

Is that something you are aware of?
is there a way for me to not get the environment marked as having changed between two consecutive doc builds (with no change in between them of course).
I'd like Sphinx to limit API generation to only what has been modified.

Thanks!

📝 Steps to reproduce

Reach out to me so I can demonstrate.

But if it comes from ansys-sphinx-theme then anyone should see this message between two consecutive runs of Sphinx on their doc.

💻 Which operating system are you using?

Windows

📀 Which ANSYS version are you using?

261

🐍 Which Python version are you using?

3.12

📦 Installed packages

ansys-sphinx-theme[autoapi]==1.5.2
enum-tools[sphinx]==0.13.0
graphviz==0.20.1
imageio==2.37.0
imageio-ffmpeg==0.6.0
pypandoc==1.15
pytest-sphinx==0.6.3
pyvista==0.45.2
sphinx==8.2.3
sphinx-copybutton==0.5.2
sphinx-gallery==0.19.0
sphinx-jinja==2.0.2
sphinx-notfound-page==1.1.0
sphinx-reredirects==0.1.6
sphinx_design==0.6.1
sphinxcontrib-napoleon==0.7
vtk==9.4.2

[jorgepiloto]

Hi Paul, the only thing I can suspect is that we are using hooks to modify some configuration parameters. We add those at build time to reduce maintenance on developers side. This may be the reason why you always get a notification for the configuration change.

[Revathyvenugopal162]

Hi Paul, the only thing I can suspect is that we are using hooks to modify some configuration parameters. We add those at build time to reduce maintenance on developers side. This may be the reason why you always get a notification for the configuration change.

Thank you for opening the issue Paul, I also suspect the same as @jorgepiloto mentioned. I can investigate this further by trying a few possible solutions on my end.

[Revathyvenugopal162]

The issue you've pointed out is a valid one and highlights an important concern. However, at this point, we can't entirely eliminate outdated configuration in the pickled environment by setting it to zero. While many of the AutoAPI-related settings originate from our theme, not all configuration options do. For example, html_permalinks_icon and other html_theme_options come from the PyData Sphinx theme, and static content like example pages (html_static_path) is contributed by extensions such as sphinx-design.

That said, this was a valuable insight. While we can't make our theme a completely zero-configuration environment on its own, I’ve updated this PR to remove all AutoAPI options from pickled env from our theme. This ensures that only the official AutoAPI configuration (i.e., the Jinja environment provided by AutoAPI itself) is retained in the pickled environment. SS attached in the PR description

[PProfizi]

Thanks @Revathyvenugopal162 for looking into this!

If I understood correctly, your point is that you are changing the ansys-sphinx-theme autoapi extension to make these options detected as outdated, but other extensions will probably still do so that will not solve the entire problem.
Is that right?

[Revathyvenugopal162]

Thanks @Revathyvenugopal162 for looking into this!

If I understood correctly, your point is that you are changing the ansys-sphinx-theme autoapi extension to make these options detected as outdated, but other extensions will probably still do so that will not solve the entire problem. Is that right?

yes, Most of the time, I think the issue is primarily caused by config variables being modified or updated during the build process.

[Revathyvenugopal162]

Removed all AutoAPI options from pickled env from theme https://github.com/ansys/ansys-sphinx-theme/pull/728/files

[Revathyvenugopal162]

Closing this issue, feel free to open if the autoapi related/theme related env are changing