Build fail on gitlab CI job

[cjeanner]

Hello,

First, thank you for taking that project over - sphinx really needs proper multi-version support, outside of RTD.

Issue context:
We have a "docs" repository hosted on a GitLab instance, and we're having a CI job building the doc upon merge-requests (equivalent of the pull-request + github workflow).

Maybe I'm missing some options or something? Thank you for your help!

Versions of sphinx related packages:

$ pip freeze | grep sphinx
sphinx-autobuild==2024.2.4
sphinx-rtd-theme==2.0.0
sphinx-versioned-docs==1.2
sphinx_collapse==0.1.2
sphinxcontrib-applehelp==1.0.8
sphinxcontrib-devhelp==1.0.6
sphinxcontrib-htmlhelp==2.0.5
sphinxcontrib-jquery==4.1
sphinxcontrib-jsmath==1.0.1
sphinxcontrib-qthelp==1.0.7
sphinxcontrib-serializinghtml==1.1.10
sphinxemoji==0.3.1

The job is configured as follow:

build-test:
  only:
    - merge_requests
  stage: ensure-build
  script: &script
    - make ci_build
  artifacts:
    expose_as: 'Docs preview'
    paths:
      - public/index.html
      - public

The make ci_build is as follow:

SPHINXBUILD       = sphinx-versioned
BUILDDIR              = ./public
ALLSPHINXOPTS  = --chdir sources -O $(BUILDDIR) --git-root ./ --local-conf ./sources/conf.py

.PHONY: ci_build
ci_build:
        $(SPHINXBUILD) $(ALLSPHINXOPTS)
        @echo
        @echo "Build finished. The HTML pages are in $(BUILDDIR)."

The issue looks like this (full output):

$ make ci_build
sphinx-versioned --chdir sources -O ./public --git-root ./ --local-conf ./sources/conf.py
| SUCCESS  | - latched into the git repo
| SUCCESS  | - located conf.py
| INFO     | - Pre-building...
╭───────────────────── Traceback (most recent call last) ──────────────────────╮
│ /usr/local/lib/python3.11/site-packages/sphinx_versioned/__main__.py:307 in  │
│ main                                                                         │
│                                                                              │
│   304 │                                                                      │
│   305 │   log.remove()                                                       │
│   306 │   log.add(sys.stderr, format=logger_format, level=loglevel.upper())  │
│ ❱ 307 │   return VersionedDocs(locals())                                     │
│   308                                                                        │
│   309                                                                        │
│   310 if __name__ == "__main__":                                             │
│                                                                              │
│ ╭──────────────────── locals ─────────────────────╮                          │
│ │                     chdir = 'sources'           │                          │
│ │                  git_root = './'                │                          │
│ │                local_conf = './sources/conf.py' │                          │
│ │                  loglevel = 'info'              │                          │
│ │               main_branch = 'main'              │                          │
│ │                output_dir = './public'          │                          │
│ │                  prebuild = True                │                          │
│ │                     quite = True                │                          │
│ │ reset_intersphinx_mapping = False               │                          │
│ │           select_branches = None                │                          │
│ │      sphinx_compatibility = False               │                          │
│ │                   verbose = False               │                          │
│ ╰─────────────────────────────────────────────────╯                          │
│                                                                              │
│ /usr/local/lib/python3.11/site-packages/sphinx_versioned/__main__.py:57 in   │
│ __init__                                                                     │
│                                                                              │
│    54 │   │   self._versions_to_pre_build = (                                │
│    55 │   │   │   self._select_specific_branches() if self.select_branches e │
│    56 │   │   )                                                              │
│ ❱  57 │   │   self._pre_build()                                              │
│    58 │   │                                                                  │
│    59 │   │   # Adds our extension to the sphinx-config                      │
│    60 │   │   application.Config = ConfigInject                              │
│                                                                              │
│ ╭───────────────────────────────── locals ─────────────────────────────────╮ │
│ │ config = {                                                               │ │
│ │          │   'chdir': 'sources',                                         │ │
│ │          │   'output_dir': './public',                                   │ │
│ │          │   'git_root': './',                                           │ │
│ │          │   'local_conf': './sources/conf.py',                          │ │
│ │          │   'reset_intersphinx_mapping': False,                         │ │
│ │          │   'sphinx_compatibility': False,                              │ │
│ │          │   'prebuild': True,                                           │ │
│ │          │   'select_branches': None,                                    │ │
│ │          │   'main_branch': 'main',                                      │ │
│ │          │   'quite': True,                                              │ │
│ │          │   ... +2                                                      │ │
│ │          }                                                               │ │
│ │   self = <sphinx_versioned.__main__.VersionedDocs object at              │ │
│ │          0x7f9630dfca90>                                                 │ │
│ ╰──────────────────────────────────────────────────────────────────────────╯ │
│                                                                              │
│ /usr/local/lib/python3.11/site-packages/sphinx_versioned/__main__.py:195 in  │
│ _pre_build                                                                   │
│                                                                              │
│   192 │   │   log.info("Pre-building...")                                    │
│   193 │   │                                                                  │
│   194 │   │   # get active branch                                            │
│ ❱ 195 │   │   self._active_branch = self.versions.active_branch              │
│   196 │   │                                                                  │
│   197 │   │   for tag in self._versions_to_pre_build:                        │
│   198 │   │   │   log.info(f"pre-building: {tag}")                           │
│                                                                              │
│ ╭───────────────────────────────── locals ─────────────────────────────────╮ │
│ │ self = <sphinx_versioned.__main__.VersionedDocs object at                │ │
│ │        0x7f9630dfca90>                                                   │ │
│ ╰──────────────────────────────────────────────────────────────────────────╯ │
│                                                                              │
│ /usr/local/lib/python3.11/site-packages/sphinx_versioned/versions.py:94 in   │
│ active_branch                                                                │
│                                                                              │
│    91 │   │   """Property to get active_branch."""                           │
│    92 │   │   if self._active_branch:                                        │
│    93 │   │   │   return self._active_branch                                 │
│ ❱  94 │   │   return self.repo.active_branch                                 │
│    95 │                                                                      │
│    96 │   pass                                                               │
│    97                                                                        │
│                                                                              │
│ ╭───────────────────────────────── locals ─────────────────────────────────╮ │
│ │   args = ()                                                              │ │
│ │ kwargs = {}                                                              │ │
│ │   self = <sphinx_versioned.versions.GitVersions object at                │ │
│ │          0x7f963071a390>                                                 │ │
│ ╰──────────────────────────────────────────────────────────────────────────╯ │
│                                                                              │
│ /usr/local/lib/python3.11/site-packages/git/repo/base.py:958 in              │
│ active_branch                                                                │
│                                                                              │
│    955 │   │   :return: Head to the active branch                            │
│    956 │   │   """                                                           │
│    957 │   │   # reveal_type(self.head.reference)  # => Reference            │
│ ❱  958 │   │   return self.head.reference                                    │
│    959 │                                                                     │
│    960 │   def blame_incremental(self, rev: str | HEAD, file: str, **kwargs: │
│    961 │   │   """Iterator for blame information for the given file at the g │
│                                                                              │
│ ╭─────────────────────────── locals ───────────────────────────╮             │
│ │ self = <git.repo.base.Repo '/builds/ci-framework/docs/.git'> │             │
│ ╰──────────────────────────────────────────────────────────────╯             │
│                                                                              │
│ /usr/local/lib/python3.11/site-packages/git/refs/symbolic.py:383 in          │
│ _get_reference                                                               │
│                                                                              │
│   380 │   │   │   to a reference, but to a commit"""                         │
│   381 │   │   sha, target_ref_path = self._get_ref_info(self.repo, self.path │
│   382 │   │   if target_ref_path is None:                                    │
│ ❱ 383 │   │   │   raise TypeError("%s is a detached symbolic reference as it │
│   384 │   │   return self.from_path(self.repo, target_ref_path)              │
│   385 │                                                                      │
│   386 │   def set_reference(                                                 │
│                                                                              │
│ ╭─────────────────────────── locals ───────────────────────────╮             │
│ │            self = <git.HEAD "HEAD">                          │             │
│ │             sha = '7a54f8d50349fee51789f0336634a27c6ebd5f21' │             │
│ │ target_ref_path = None                                       │             │
│ ╰──────────────────────────────────────────────────────────────╯             │
╰──────────────────────────────────────────────────────────────────────────────╯
TypeError: HEAD is a detached symbolic reference as it points to 
'7a54f8d50349fee51789f0336634a27c6ebd5f21'
make: *** [Makefile:18: ci_build] Error 1
Cleaning up project directory and file based variables 00:01
ERROR: Job failed: exit code 1

[devanshshukla99]

Hi, glad that you found this useful

I skimmed through the exception, it seems it's related to gitpython-developers/GitPython#633.

Although, not a perfect solution, I can enclose the exc within a try-except block for now

[cjeanner]

Seeing the issue on GitPython is apparently still open, anything you could do on your side would be nice :). And, yep, with an internal project having 2 active branches, having the possibility to build docs for both of them is a great plus :).

Lemme know when/if you have a patch I may test.