Do I need to make changes to old branches or tags?
No, you don’t. sphinx-multiversion will always use the conf.py file from your currently checked out branch.
Use the conf.py file from your currently checked out branch when loading config options from other branches/tags. This change fixed an instance of the Failed load config for %s from %s for me after I changed my conf.py file.
Edit: I also found that sphinx.config.Config.init_values would give the error unknown config value %r in override, ignoring when the config.py is loaded for the tags/branches to be generated (it uses logger.warning, however it prints to stderr and many CI/CD servers fail any step with output to stderr) when overriding sphinx-multiversion config values from the command line (using -D).
When sphinx-multiversion loads the config.py file for the tags/branches, there is at least one value that might be useful to override; smv_outputdir_format. In my use case, I set it to smv_outputdir_format="{repo_name}/v{version}" when generating for release, because I only want to generate from tags. When running CI, I want to override with -D "smv_outputdir_format={ref.name}" because I care less about the output folder structure and more about also generating the current branch, which the release format does not support. I also generate for multiple versions of python, so I always want to run the branch generation through sphinx-multiversion to ensure it works, especially when adding a new version.
The fix I chose was to always add the sphinx-multiversion options to the sphinx.config by removing that code out of an if statement that prevented doing so when loading the config for branches/tags.
This is stated as how things work in the FAQ.
Use the
conf.pyfile from your currently checked out branch when loading config options from other branches/tags. This change fixed an instance of theFailed load config for %s from %sfor me after I changed myconf.pyfile.Edit: I also found that
sphinx.config.Config.init_valueswould give the errorunknown config value %r in override, ignoringwhen theconfig.pyis loaded for the tags/branches to be generated (it useslogger.warning, however it prints tostderrand many CI/CD servers fail any step with output tostderr) when overridingsphinx-multiversionconfig values from the command line (using-D).When
sphinx-multiversionloads theconfig.pyfile for the tags/branches, there is at least one value that might be useful to override;smv_outputdir_format. In my use case, I set it tosmv_outputdir_format="{repo_name}/v{version}"when generating for release, because I only want to generate from tags. When running CI, I want to override with-D "smv_outputdir_format={ref.name}"because I care less about the output folder structure and more about also generating the current branch, which the release format does not support. I also generate for multiple versions of python, so I always want to run the branch generation throughsphinx-multiversionto ensure it works, especially when adding a new version.The fix I chose was to always add the
sphinx-multiversionoptions to thesphinx.configby removing that code out of anifstatement that prevented doing so when loading the config for branches/tags.