Compatibility to Sphinx 3.x

[Paebbels]

What are the problems for this extension to be Sphinx 3.x compatible?

Installing this extension currently degrades Sphinx from 3.2.1 to 2.4.4. As Sphinx is usually full of bugs and problems, it wise to use always the latest Sphinx version.

---

/cc @eine

[speedyleion]

The main issue I know of is that sphinx 3 added new directives to the C domain and the old directives no longer work for their overloaded usage. (sphinx 3 c domain).
Previously, in the sphinx 2 c domain, one would use the .. c:function:: for function like macros, and .. c:type:: for structs, but as you can see from the output below sphinx 3 will create errors for these usages.

c:\git\c_sphinx\src\sphinx_c_autodoc\loader.py:docstring of example.c:1: WARNING: Error in declarator
If declarator-id with parameters (e.g., 'void f(int arg)'):
  Invalid C declaration: Expected identifier in nested name. [error at 13]
    MY_COOL_MACRO(_a, _b)
    -------------^
If parenthesis in noptr-declarator (e.g., 'void (*f(int arg))(double)'):
  Error in declarator or parameters
  Invalid C declaration: Expecting "(" in parameters. [error at 16]
    MY_COOL_MACRO(_a, _b)
    ----------------^

c:\git\c_sphinx\src\sphinx_c_autodoc\loader.py:docstring of example.c:1: 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 a_struct_using_member_comments
    ------^
If typedef-like declaration:
  Error in declarator or parameters
  Invalid C declaration: Expected identifier in nested name. [error at 37]
    struct a_struct_using_member_comments

[eine]

@speedyleion, it seems that macros and structs are now explicitly handled by c:macro:: and c:var::. So, my understanding of your comment is that you cannot support users targeting sphinx 2 and sphinx 3, at the same time. Users would need to use different versions of this extension explicitly. Assuming this is correct, which would be your preferred solution?

• Keep this extension compatible with Sphinx 2 only.
• Update this extension and keep it compatible with Sphinx 3 only.
• Create a new branch and keep versions for Sphinx 2 and Sphinx 3 maintained in parallel.

[speedyleion]

My vote would be to migrate to sphinx 3, dropping sphinx 2 support.

• This is still in beta and it's early enough, only been up for 4 months, that it hopefully won't affect too many.
• I probably need to double check, but I think the new directives in the c domain more cleanly cover most of the c constructs.

[speedyleion]

Doing some more digging it seems others are feeling the sphinx 2 - 3 pain for the c domain

• https://bugs.python.org/issue40204
• https://bugzilla.redhat.com/showdependencytree.cgi?id=SPHINX3&hide_resolved=1
• C domain changes of Sphinx 3 prevent to write doc compatible with Sphinx 2 and Sphinx 3 sphinx-doc/sphinx#7899

I tried the compatibility flag, c_allow_pre_v3, unfortunately it doesn't fix everything. In particular function like macros aren't supported and the way viewcode is hooked up seems to have problems with the new ASTParameters that has been added to the C domain.

From the original post by @Paebbels it seems that you all aren't on a linux distro that is stuck back on sphinx 2.
Even though it may prevent some users on older linux distros from using I would still vote for sphinx 3. If it comes down to it I think they could work around it by using tox or a virtual environment to build the documentation.

I'll try to find some time to dig through the new C domain and get an understanding of what's going on in there.

[Paebbels]

I'm running on Windows and Linux (local GitLab runners as well as Travis or ReadTheDocs). Anyhow, I force all these environments to Sphinx 3.x :).

[speedyleion]

I've released a new version on pypi, 0.3.0, which supports sphinx 3.

[eine]

Wow! That was a really fast and effective reaction. Congratulations!