What if old `conf.py` do not run successfully with the current dependencies?

[merlinND]

Hello,

Thanks for developing and maintaining this helpful extension!

Current Behavior

I understand that the current conf.py is used to build all of the versions. That makes sense.

However, what is not mentioned in the docs (I believe) is that the conf.py file of each branch will be loaded in order to extract some metadata.
Unfortunately, due to changing dependencies, APIs, or any other reasons, conf.py files on old branches may not run successfully given the dependencies of the latest version. In that case, the documentation of those versions is not built.

Expected Behavior

From the documentation, I expected old conf.py files to not be loaded at all.

Otherwise, there needs to be some kind of mechanism to:

• Install older dependency versions,
• Or have some kind of pre-run callback so that we have the opportunity to run some code (e.g. to monkey-patch some dependencies) before each old conf.py is imported.
  • The callback could receive the git tag / branch / commit and current temporary directory (checkout) as argument.
  • The user might even patch some of the source files in the temporary folder using that callback..

...so that old tags can be kept intact and still build correctly.

As it stands, I don't see any existing mechanism to work around this. Please let me know if there's an existing solution.

Environment

• OS: Ubuntu 24.04
• Python: 3.10.16
• Project Version (or commit ID): abcc9b8

[whompyjaw]

Ya I am running into this issue right now. I am trying to retrofit this tool to generate docs for a repo that did not originally have a docs directory. It would just be nice if there was a way to print out what exactly the error is so we can change the conf.py in the old branches. Instead of the ambiguous and unhelpful message we get.

I am not entirely sure if this is a "solutino", but i commented out everything in my conf.py in the branch that was breaking the sphinx build and that allowed me to run the command successfully.