qemu docs fails to build with Sphinx 3.0.x

[Stig-Ørjan Smelror]

We've just updated Sphinx to version 3.0.1 and qemu fails to build the docs with this version.

Here's the relevant section in the build log.

CONFDIR="/etc/qemu" /usr/bin/sphinx-build-3 -W -b html -D version=4.2.92 -D release="4.2.92 (qemu-5.0.0-0.rc2.0.1.mga8)" -d .doctrees/devel-html /home/iurt/rpmbuild/BUILD/qemu-5.0.0-rc2/docs/devel docs/devel
Running Sphinx v3.0.1
making output directory... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 14 source files that are out of date
updating environment: [new config] 14 added, 0 changed, 0 removed
reading sources... [ 7%] bitops
reading sources... [ 14%] decodetree
reading sources... [ 21%] index
reading sources... [ 28%] kconfig
reading sources... [ 35%] loads-stores
reading sources... [ 42%] memory
reading sources... [ 50%] migration
reading sources... [ 57%] reset
reading sources... [ 64%] s390-dasd-ipl
reading sources... [ 71%] secure-coding-practices
reading sources... [ 78%] stable-process
reading sources... [ 85%] tcg
reading sources... [ 92%] tcg-plugins
reading sources... [100%] testing

Warning, treated as error:
/home/iurt/rpmbuild/BUILD/qemu-5.0.0-rc2/docs/../include/exec/memory.h:3:Type must be either just a name or a typedef-like declaration.
If just a name:
  Error in declarator or parameters
  Invalid C declaration: Expected identifier in nested name, got keyword: struct [error at 6]
    struct MemoryListener
    ------^
If typedef-like declaration:
  Error in declarator or parameters
  Invalid C declaration: Expected identifier in nested name. [error at 21]
    struct MemoryListener
    ---------------------^

make: *** [Makefile:1095: docs/devel/index.html] Error 2
make: *** Waiting for unfinished jobs....

I found this commit for memory.h that includes the section that faults.
https://github.com/qemu/qemu/commit/5d248213180749e674fbccbacc6ee9c38499abb3#diff-d892cbf314945b44699534cc1de4ebbd

You can see the whole build log here.
https://pkgsubmit.mageia.org/uploads/failure/cauldron/core/release/20200410161120.tv.duvel.699/log/qemu-5.0.0-0.rc2.0.1.mga8/build.0.20200410161338.log

System: Mageia Cauldron

[Peter Maydell (pmaydell)]

Hmm, that's not ideal. The C is valid C which the compiler accepts, so I'm not sure what Sphinx is complaining about, and I don't have a system with that new a version of Sphinx.

It does suggest that we ought to make our configure --enable-werror/--disable-werror (and the code that makes the default be disable for releases) control Sphinx's warnings-as-errors option as well as the compiler's, which would at least mean that for released versions the build doesn't fail entirely on Sphinx warnings.

[Stig-Ørjan Smelror (kekepower)]

One of our packaging gurus make a small change that removed the error fails option.

# Don't treat warnings as errors when building docs with sphinx
sed -i -e '/SPHINX_BUILD/s/-W//' Makefile

The build completes now, however there are still errors.

CONFDIR="/etc/qemu" /usr/bin/sphinx-build-3 -b html -D version=4.2.92 -D release="4.2.92 (qemu-5.0.0-0.rc2.0.1.mga8)" -d .doctrees/devel-html /home/iurt/rpmbuild/BUILD/qemu-5.0.0-rc2/docs/devel docs/devel
Running Sphinx v3.0.1
making output directory... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 14 source files that are out of date
updating environment: [new config] 14 added, 0 changed, 0 removed
reading sources... [ 7%] bitops
reading sources... [ 14%] decodetree
reading sources... [ 21%] index
reading sources... [ 28%] kconfig
reading sources... [ 35%] loads-stores
reading sources... [ 42%] memory
reading sources... [ 50%] migration
reading sources... [ 57%] reset
reading sources... [ 64%] s390-dasd-ipl
reading sources... [ 71%] secure-coding-practices
reading sources... [ 78%] stable-process
reading sources... [ 85%] tcg
reading sources... [ 92%] tcg-plugins
reading sources... [100%] testing

/home/iurt/rpmbuild/BUILD/qemu-5.0.0-rc2/docs/../include/exec/memory.h:3: WARNING: Type must be either just a name or a typedef-like declaration.
If just a name:
  Error in declarator or parameters
  Invalid C declaration: Expected identifier in nested name, got keyword: struct [error at 6]
    struct MemoryListener
    ------^
If typedef-like declaration:
  Error in declarator or parameters
  Invalid C declaration: Expected identifier in nested name. [error at 21]
    struct MemoryListener
    ---------------------^

/home/iurt/rpmbuild/BUILD/qemu-5.0.0-rc2/docs/../include/exec/memory.h:428: WARNING: Type must be either just a name or a typedef-like declaration.
If just a name:
  Error in declarator or parameters
  Invalid C declaration: Expected identifier in nested name, got keyword: struct [error at 6]
    struct AddressSpace
    ------^
If typedef-like declaration:
  Error in declarator or parameters
  Invalid C declaration: Expected identifier in nested name. [error at 19]
    struct AddressSpace
    -------------------^

/home/iurt/rpmbuild/BUILD/qemu-5.0.0-rc2/docs/../include/exec/memory.h:673: WARNING: Type must be either just a name or a typedef-like declaration.
If just a name:
  Error in declarator or parameters
  Invalid C declaration: Expected identifier in nested name, got keyword: struct [error at 6]
    struct MemoryRegionSection
    ------^
If typedef-like declaration:
  Error in declarator or parameters
  Invalid C declaration: Expected identifier in nested name. [error at 26]
    struct MemoryRegionSection
    --------------------------^

/home/iurt/rpmbuild/BUILD/qemu-5.0.0-rc2/docs/../include/exec/memory.h:834: WARNING: Error in declarator or parameters
Invalid C declaration: Expecting "," or ")" in parameters, got "EOF". [error at 208]
  void memory_region_init_resizeable_ram (MemoryRegion * mr, struct Object * owner, const char * name, uint64_t size, uint64_t max_size, void (*resized) (const char*, uint64_t length, void *host, Er...

[Peter Maydell (pmaydell)]

I'm a bit confused: you say "however there are still errors" but the build log you quote ends with "build succeeded, 4 warnings" and it looks like it has indeed just produced warnings and continued.

[Stig-Ørjan Smelror (kekepower)]

You are right. Wrong choice of words.

However, the change is a breaking change from Sphinx.

See https://github.com/sphinx-doc/sphinx/issues/7457#issuecomment-612413080

[Peter Maydell (pmaydell)]

I've sent a proposed fix to the list:
https://<email address hidden>/

[Peter Maydell (pmaydell)]

The upstream fix for this is now in 5.0-rc3 and will be in the final 5.0 release.