sphinx-build documentation warnings and errors with newer versions of Sphinx

[esabol]

Sphinx v1.8.5 on Ubuntu 20.04 works fine as it always has, but Sphinx v4.3.2 on Ubuntu 22.04 and v5.3.0 on Alpine 3.17 emit the following warnings (actually one is an error!):

reading sources... [100%] protocol/text
/__w/gearmand/gearmand/docs/source/libgearman.rst:63: WARNING: Duplicate C declaration, also defined at libgearman:59.
Declaration is '.. c:macro:: GEARMAN_DEFAULT_TCP_PORT'.
/__w/gearmand/gearmand/docs/source/libgearman/gearman_return_t.rst:188: WARNING: Duplicate C declaration, also defined at libgearman/gearman_return_t:129.
Declaration is '.. c:type:: GEARMAN_WORK_FAIL'.
/__w/gearmand/gearmand/docs/source/libgearman/gearman_return_t.rst:206: WARNING: Duplicate C declaration, also defined at libgearman/gearman_return_t:42.
Declaration is '.. c:type:: GEARMAN_SUCCESS'.
/__w/gearmand/gearmand/docs/source/libgearman/gearman_string_t.rst:13: WARNING: Invalid C declaration: Expected end of definition. [error at 7]
  size_t gearman_size(gearman_string_t)
  -------^
/__w/gearmand/gearmand/docs/source/libgearman/gearman_string_t.rst:15: WARNING: Invalid C declaration: Expected identifier in nested name, got keyword: const [error at 5]
  const char *gearman_c_str(gearman_string_t)
  -----^
/__w/gearmand/gearmand/docs/source/libgearman/types.rst:5: ERROR: Unknown directive type "highlightlang".
.. highlightlang:: c
/__w/gearmand/gearmand/docs/source/libgearman/types.rst:13: 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, got user-defined keyword: bool. Remove it from c_extra_keywords to allow it as identifier.
  Currently c_extra_keywords is ['alignas', 'alignof', 'bool', 'complex', 'imaginary', 'noreturn', 'static_assert', 'thread_local']. [error at 4]
    bool
    ----^
If typedef-like declaration:
  Error in declarator or parameters
  Invalid C declaration: Expected identifier in nested name. [error at 4]
    bool
    ----^
/__w/gearmand/gearmand/docs/source/libgearman/types.rst:27: 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 timespec
    ------^
If typedef-like declaration:
  Error in declarator or parameters
  Invalid C declaration: Expected identifier in nested name. [error at 15]
    struct timespec
    ---------------^

It would be nice to clean these up, but I have no experience with Sphinx. Anyone have a clue?

[esabol]

Similar issue occurred with the Linux kernel documentation. This thread is worth reading:

https://lore.kernel.org/all/564cbd05-8788-9223-1ecc-59e7fc41b46a@gmail.com/

Some of the warnings seem to stem from structs/typedefs/enums/functions having the same name. The solution seems to be to add different sphinx-doc namespaces to them. I'm not sure how to do that yet though. More research (or help) needed.

It's possible some of these warnings might go away on their own if the sphinx-doc developers would ever merge this 3-year-old PR: sphinx-doc/sphinx#8313