0

I am trying to create a versions drop-down in Sphinx by adding a _templates/versions.html file. Although when I make html, I see the branch name in my local index.html file. Used the code for versions.html from this stackoverflow post.

Problems I am facing:

  1. When I click the main branch link from the local index.html drop-down, it redirects to file:///main/. Not sure if this is the expected behavior and if it works fine when I push the code to origin.

  2. When I commit my code to Git, I am getting below TypeError. Although my branch is pointing to HEAD.

On my Github repo, the latest commit hash is showing: 4549ac9.

$ git log --all --oneline
4549ac9 (HEAD -> main, origin/main, origin/dev, origin/HEAD, dev) added yaml
46b2373 initial changes
9ff28c9 Initial commit

Error trace from Readthedocs build: (Not sure what should HEAD point to in my case & how to fix this)

Traceback (most recent call last):
File "/home/docs/checkouts/readthedocs.org/user_builds/sphinx-ver/envs/latest/lib/python3.9/site-packages/sphinx/config.py", line 347, in eval_config_file
    exec(code, namespace)
  File "/home/docs/checkouts/readthedocs.org/user_builds/sphinx-ver/checkouts/latest/docs/conf.py", line 86, in <module>
    current_version = repo.active_branch.name
  File "/home/docs/checkouts/readthedocs.org/user_builds/sphinx-ver/envs/latest/lib/python3.9/site-packages/git/repo/base.py", line 797, in active_branch
    return self.head.reference
  File "/home/docs/checkouts/readthedocs.org/user_builds/sphinx-ver/envs/latest/lib/python3.9/site-packages/git/refs/symbolic.py", line 294, in _get_reference
    raise TypeError("%s is a detached symbolic reference as it points to %r" % (self, sha))
TypeError: HEAD is a detached symbolic reference as it points to '4549ac97308ea4fe0fc2b8def2ba509ce536db29'

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/sphinx-ver/envs/latest/lib/python3.9/site-packages/sphinx/cmd/build.py", line 272, in build_main
    app = Sphinx(args.sourcedir, args.confdir, args.outputdir,
  File "/home/docs/checkouts/readthedocs.org/user_builds/sphinx-ver/envs/latest/lib/python3.9/site-packages/sphinx/application.py", line 201, in __init__
    self.config = Config.read(self.confdir, confoverrides or {}, self.tags)
  File "/home/docs/checkouts/readthedocs.org/user_builds/sphinx-ver/envs/latest/lib/python3.9/site-packages/sphinx/config.py", line 169, in read
    namespace = eval_config_file(filename, tags)
  File "/home/docs/checkouts/readthedocs.org/user_builds/sphinx-ver/envs/latest/lib/python3.9/site-packages/sphinx/config.py", line 360, in eval_config_file
    raise ConfigError(msg % traceback.format_exc()) from exc
sphinx.errors.ConfigError: There is a programmable error in your configuration file:
torek
  • 448,244
  • 59
  • 642
  • 775
Sushivam
  • 2,537
  • 4
  • 15
  • 25
  • This isn't a Git error (there's nothing fundamentally wrong with a detached HEAD) so it must be a sphynx / read-the-docs error, that doesn't like this mode. Why it is in this mode is the next question (to which I have no idea what the answer is, this must also be a non-Git issue; *your* repository is in normal, non-detached, mode). Side note: whoever wrote the error message got it wrong, it's not a "detached symbolic reference", it's just a "detached HEAD" (making it *not* symbolic). – torek Aug 21 '22 at 18:39

1 Answers1

1

It seems that you are using gitpython in your conf.py file and it's failing at the line

current_version = repo.active_branch.name

I found an issue opened on gitpython at https://github.com/gitpython-developers/GitPython/issues/633 that talks about this problem. I'd suggest you to read that issue and see if you find something useful there. Otherwise, you may ask them about your particular problem.

This does not seem to be a problem related to Sphinx or Read the Docs, but with your configuration and usage of gitpython.

Manuel Kaufmann
  • 346
  • 1
  • 7