Re: linux-next: build failure after upgrading sphinx

[Markus Heiser <markus.heiser@darmarit.de>]

Am 31.08.20 um 21:03 schrieb Jonathan Corbet:
> On Thu, 27 Aug 2020 14:50:17 +1000
> Stephen Rothwell <sfr@canb.auug.org.au> wrote:
> 
>> Today I upgraded ot sphinx v3.2.1 and got the following error from
>> "make htmldocs":
>>
>> Running Sphinx v3.2.1
>> enabling CJK for LaTeX builder
>>
>> Extension error:
>> Could not import extension cdomain (exception: cannot import name 'c_funcptr_sig_re' from 'sphinx.domains.c' (/usr/lib/python3/dist-packages/sphinx/domains/c.py))
>>
>> I have downgraded to version 2.4.3 and await suggestions/patches :-)
> 
> [Adding Markus]
> 
> Markus, this looks like an issue with the "handle function-like macros"
> code that has your name on it.  The Sphinx folks think that functionality
> can just be removed:
> 
> 	https://github.com/sphinx-doc/sphinx/issues/7421
> 
> Do you agree?  We need to look at what they're saying about the :name:
> directive as well; somehow I missed that when it first went in.
> 
> Thanks,
> 
> jon

Hi Jon, thanks for taking me into CC.

I guess you refer this post:

   https://github.com/sphinx-doc/sphinx/issues/7421#issuecomment-609830660

What I know is: The Sphinx >= v3.0 includes a "C, initial
rewrite" which is not downward compatible.

  https://github.com/sphinx-doc/sphinx/commit/0f49e30c#diff-59e33b0

---

To give an short answer to opener's question:

Our Sphinx-build is not Sphinx >= v3.0 ready.  We recommend
to follow our installation instructions [1] and install
requirements by::

   (virtualenv) $ pip install -r Documentation/sphinx/requirements.txt

In the requirements.txt we stick Sphinx at 'Sphinx==2.4.4'.
In my personal opinion there are more problems than just the
C-domain when using other Sphinx Versions (e.g. PDF is most
often problematic).

[1] https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html#sphinx-install

---

I can't say if this *rewrite* has a better "handle
function-like macros" or not.

Since the changes are not downward compatible,
Documentation/sphinx/cdomain.py needs a rewrite
(Unfortunately, I hadn't had the time to do this).

TL;DR;

In my linuxdoc [2] project I use the same cdomain.py
implementation and split cdomain into v2 and v3 [3].  ATM
linuxdoc/cdomainv3.py is just a skeleton which is used in
Sphinx >= v3.0 installations.  My experience is, that it
spits out more noise, but I haven't had time to look closer
right now.

[2] https://return42.github.io/linuxdoc
[3] https://github.com/return42/linuxdoc/commit/70673dc


   -- Markus --