Avoiding "No matching refs found!" when sourcedir and confdir aren't in git yet

[pdurbin]

Today I found myself copying over an existing, working sphinx-multiversion setup to a git project where Sphinx hasn't been used yet. (Docs have been in a dedicated repo and we're considering moving them to a "docs" directory in the main repo.)

sphinx-build docs build/html worked fine but when I went to do sphinx-multiversion docs build/html I got the following error:

No matching refs found!

A debug message in git.py provided a clue:

Skipping 'refs/heads/main' because it lacks required files: ['docs/source', 'docs/source/conf.py']

After making an initial commit of my "docs" directory, sphinx-multiversion docs build/html worked fine.

Perhaps a heads up about this could be added to the documentation?

Thanks for sphinx-multiversion!

[snorkman88]

Can you please elaborate a bit more on how to avoid this issue? I am facing this only when running on GHA but locally with act everything works fine.

[pdurbin]

@snorkman88 I'm sorry but I'm not personally using sphinx-multiversion anymore so I'm going to close this issue.

You might be interested in checking out this GitHub Action, which uses sphinx-multiversion (see the make versions command): https://github.com/opendp/opendp/blob/v0.6.1/.github/workflows/docs.yml#L96

The live docs are here: https://docs.opendp.org

[snorkman88]

After investigating a little bit further about the message "No matching refs found", I think it worths mentioning the problems I faced were mainly caused because the git tags expected to be built were not present on the GHA.

Adding the following line to the GHA before invoking sphinx-multiversion did the job.

@Holzhaus don't you think it would be a good idea to clarify this particular case in the doku page?