GDAL 3.1.0 fails to build with Sphinx 3.0.4

[ggardet]

Expected behavior and actual behavior.

GDAL 3.1.0 fails to build with Sphinx 3.0.4 with the following error:

[  505s] Sphinx parallel build error:
[  505s] UnboundLocalError: local variable 'declaration' referenced before assignment

Steps to reproduce the problem.

Try to build GDAL 3.1.0, with patch from #2678, with Sphinx 3.0.4.

Operating system

openSUSE Tumbleweed

GDAL version and provenance

3.1.0 from openSUSE, with patch from #2678

[mloskot]

gdal/gdal/doc/requirements.txt

Lines 3 to 4 in 4d2a82e

	breathe == 4.13.0
	sphinx == 2.0.1

[ggardet]

gdal/gdal/doc/requirements.txt

Lines 3 to 4 in 4d2a82e

	breathe == 4.13.0
	sphinx == 2.0.1

From a distribution point of view, you cannot be limited to specific versions of deps.

[rouault]

This might be a Breathe issue according to breathe-doc/breathe#534 . Try upgrading to Breathe v4.19.2

(For the purpose of doc building, one possibility would be to build in a Python venv with versions of the modules different from the one shipped by the distributon)

[ggardet]

I use Breathe v4.19.1, so I will try to upgrade to Breathe v4.19.2.

[tigerfoot]

About building in venv, its just not possible. The secure build made on openSUSE is done in a one time build vm which once setup (all needed packages and deps declared in the spec files loaded) will not have network access for obvious reason and build is done with an unprivileged user.

I guess that if the majority of the doc would benefit to a separate build (we could organize another spec) if there's a dedicated doc tar gz build for. We need (to satisfy quality rules) to provide the man for each binary. But even thoses I'm not sure every binary or script published in /usr/bin has one corresponding man file.

[rouault]

We need (to satisfy quality rules) to provide the man for each binary. But even thoses I'm not sure every binary or script published in /usr/bin has one corresponding man file.

There should be. There were a few missing in 3.1.0 for new utilities (gdalmdminfo, gdalmdimtranslate), but this has been adressed in 3.1.1RC1.

The man pages are already generated in the tarball. And there's a pre generated for .0 versions when it is not convenient for people to build the HTML docs by themselves (http://download.osgeo.org/gdal/3.1.0/gdal310doc.zip)

[tigerfoot]

@rouault excellent news for the man and the doc. This will allow us to minimize the BuildRequirement of the spec and thus make it more robust to software changes happening all the time in TW. Also this will decrease the number of rebuild.
I will look to split gdal-doc and gdal for the 3.1.1 release.

[jmckenna]

On this Windows side I've also had to separate the doc build process from the GDAL source build steps, it's the only way to keep your sanity each build time for GDAL 3 :)

[rouault]

Closing assuming it is a now resolved Breathe issue

[ggardet]

I confirm that breathe v4.19.2 fixes the problem! Thanks.