classification
Title: Docs fail to build with Sphinx 4 due to Invalid C declaration
Type: behavior Stage: resolved
Components: Documentation Versions: Python 3.11, Python 3.10, Python 3.9
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: mark.dickinson Nosy List: docs@python, ksurma, mark.dickinson, mcepl, miss-islington
Priority: normal Keywords: patch

Created on 2021-06-15 12:42 by ksurma, last changed 2021-06-23 09:12 by mark.dickinson. This issue is now closed.

Files
File name Uploaded Description Edit
bpo44426-complex-keyword-sphinx.patch mcepl, 2021-06-18 23:01
Pull Requests
URL Status Linked Edit
PR 26744 merged mark.dickinson, 2021-06-15 19:04
PR 26760 merged miss-islington, 2021-06-16 17:44
PR 26761 merged miss-islington, 2021-06-16 17:44
PR 26798 merged mark.dickinson, 2021-06-19 08:50
PR 26804 merged miss-islington, 2021-06-19 14:32
PR 26805 merged miss-islington, 2021-06-19 14:32
Messages (19)
msg395874 - (view) Author: Karolina Surma (ksurma) Date: 2021-06-15 12:42
Hello all,
I want to build Python 3.10~b2 documentation using Sphinx 4.0.2 (released in May 2021) as RPM in Fedora with aim to ship it in Fedora 35.

The build fails with the following error:

Warning, treated as error:
/builddir/build/BUILD/Python-3.10.0b2/Doc/c-api/complex.rst:49:Error in declarator or parameters
Error in declarator or parameters
Invalid C declaration: Expected identifier, got keyword: complex [error at 39]
  Py_complex _Py_c_neg(Py_complex complex)
  ---------------------------------------^
make: *** [Makefile:51: build] Error 2


The Sphinx changelog mentions in Bug fixes in https://www.sphinx-doc.org/en/master/changes.html#id21 the likely cause:
C, properly reject function declarations when a keyword is used as parameter name.
msg395888 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2021-06-15 18:05
Hmm. It's probably not the best name, and we can certainly change it.

But I'm a bit confused by the error message: `complex` isn't a keyword in either C or C++, so I'm not sure why Sphinx thinks it is.
msg395889 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2021-06-15 18:14
As a test, gcc and clang both seem happy to treat this as valid C.  I think Sphinx is wrong to reject this.

mdickinson@mirzakhani Desktop % cat test.c
typedef struct {
    double real;
    double imag;
} Py_complex;

Py_complex _Py_c_neg(Py_complex complex);
mdickinson@mirzakhani Desktop % gcc -Wall -Wextra -std=c17 -c test.c
mdickinson@mirzakhani Desktop % clang -Wall -Wextra -std=c17 -c test.c
mdickinson@mirzakhani Desktop %
msg395952 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2021-06-16 17:43
New changeset 7247f6f433846c6e37308a550e8e5eb6be379856 by Mark Dickinson in branch 'main':
bpo-44426: Use of 'complex' as a C variable name confuses Sphinx; change it to 'num'. (GH-26744)
https://github.com/python/cpython/commit/7247f6f433846c6e37308a550e8e5eb6be379856
msg395955 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2021-06-16 19:13
New changeset c689e0a7e2a25621da82f22cc64d089eae05e753 by Miss Islington (bot) in branch '3.10':
bpo-44426: Use of 'complex' as a C variable name confuses Sphinx; change it to 'num'. (GH-26744) (GH-26760)
https://github.com/python/cpython/commit/c689e0a7e2a25621da82f22cc64d089eae05e753
msg395956 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2021-06-16 19:13
New changeset 686c6f303a6e9e54b50401be0ae3dc6aa2fcf05a by Miss Islington (bot) in branch '3.9':
bpo-44426: Use of 'complex' as a C variable name confuses Sphinx; change it to 'num'. (GH-26744) (GH-26761)
https://github.com/python/cpython/commit/686c6f303a6e9e54b50401be0ae3dc6aa2fcf05a
msg395957 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2021-06-16 19:15
> and we can certainly change it

Done. Closing here, but I've opened a Sphinx issue at https://github.com/sphinx-doc/sphinx/issues/9354
msg395980 - (view) Author: Karolina Surma (ksurma) Date: 2021-06-17 09:12
Thanks for the fix, this indeed worked. Documentation however still doesn't build successfully, this time with a traceback:

Warning, treated as error:
/builddir/build/BUILD/Python-3.10.0b2/Doc/c-api/object.rst:314:Error in declarator or parameters
Error in declarator or parameters
Invalid C declaration: Expected identifier, got keyword: default [error at 62]
  Py_ssize_t PyObject_LengthHint(PyObject *o, Py_ssize_t default)
  --------------------------------------------------------------^
make: *** [Makefile:51: build] Error 2

I'm afraid there will be more on the way as this item is resolved.
msg395986 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2021-06-17 10:16
Thanks. That one's a genuine keyword. Looks like what we probably need to do is get a list of all these errors, so that they can all be fixed at once. Presumably running without the "-W" flag would make that easier.
msg395997 - (view) Author: Karolina Surma (ksurma) Date: 2021-06-17 11:50
Thanks for the suggestion, I reran the build without -W option. 

Fortunately, the output shows that the reported errors shall be the only ones.

Build logs from the test build for reference: https://download.copr.fedorainfracloud.org/results/ksurma/pygments-2.9.0/fedora-rawhide-x86_64/02257459-python3-docs/build.log.gz
msg396013 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2021-06-17 17:07
Thanks; this looks like an easy fix, then. No time right now, but I'll aim to get to it at some point before the end of the weekend, if no-one beats me to it.
msg396106 - (view) Author: Matej Cepl (mcepl) * Date: 2021-06-18 23:01
Actually, for 3.8.10 I had to add one more keyword which confused Sphinx: default.
msg396119 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2021-06-19 09:03
Fixed in GH-26798 (not yet merged). With that change, the documentation builds cleanly for me with Python 3.9.5 / Sphinx 4.0.2 / blurb 1.0.8 / python-docs-theme 2021.5, using the command

$ python -m sphinx -b html -W . build/html
msg396133 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2021-06-19 14:32
New changeset 291848195f85e23c01adb76d5a0ff9c6eb7f2614 by Mark Dickinson in branch 'main':
bpo-44426: Fix use of the C keyword 'default' as a variable name (GH-26798)
https://github.com/python/cpython/commit/291848195f85e23c01adb76d5a0ff9c6eb7f2614
msg396134 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2021-06-19 15:16
New changeset 139c5778c26aaf25b51fcfabd88c99ba728beaea by Miss Islington (bot) in branch '3.10':
bpo-44426: Fix use of the C keyword 'default' as a variable name (GH-26798) (GH-26804)
https://github.com/python/cpython/commit/139c5778c26aaf25b51fcfabd88c99ba728beaea
msg396135 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2021-06-19 15:16
New changeset 533bff4e9fe221a7c9cf12795fd2d002e87bfa6a by Miss Islington (bot) in branch '3.9':
bpo-44426: Fix use of the C keyword 'default' as a variable name (GH-26798) (GH-26805)
https://github.com/python/cpython/commit/533bff4e9fe221a7c9cf12795fd2d002e87bfa6a
msg396164 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2021-06-20 07:10
I think this should be good now.
msg396386 - (view) Author: Karolina Surma (ksurma) Date: 2021-06-23 08:37
It looks good on my end, documentation builds just fine. Thank you!
msg396393 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2021-06-23 09:12
Thanks! Closing.
History
Date User Action Args
2021-06-23 09:12:41mark.dickinsonsetstatus: open -> closed

messages: + msg396393
2021-06-23 08:37:19ksurmasetstatus: pending -> open

messages: + msg396386
2021-06-20 07:10:15mark.dickinsonsetstatus: open -> pending
resolution: fixed
messages: + msg396164

stage: patch review -> resolved
2021-06-19 15:16:41mark.dickinsonsetmessages: + msg396135
2021-06-19 15:16:16mark.dickinsonsetmessages: + msg396134
2021-06-19 14:32:42mark.dickinsonsetmessages: + msg396133
2021-06-19 14:32:38miss-islingtonsetpull_requests: + pull_request25386
2021-06-19 14:32:33miss-islingtonsetnosy: + miss-islington
pull_requests: + pull_request25385
2021-06-19 09:03:00mark.dickinsonsetmessages: + msg396119
2021-06-19 08:50:01mark.dickinsonsetstage: resolved -> patch review
pull_requests: + pull_request25379
2021-06-18 23:01:56mceplsetfiles: + bpo44426-complex-keyword-sphinx.patch
nosy: + mcepl
messages: + msg396106

2021-06-18 11:53:03mark.dickinsonsetassignee: docs@python -> mark.dickinson
2021-06-17 17:07:14mark.dickinsonsetmessages: + msg396013
2021-06-17 11:50:32ksurmasetmessages: + msg395997
2021-06-17 10:16:29mark.dickinsonsetmessages: + msg395986
2021-06-17 09:12:39ksurmasetstatus: closed -> open
resolution: fixed -> (no value)
messages: + msg395980
2021-06-16 19:15:15mark.dickinsonsetstatus: open -> closed

versions: + Python 3.9, Python 3.11
nosy: - miss-islington

messages: + msg395957
resolution: fixed
stage: patch review -> resolved
2021-06-16 19:13:56mark.dickinsonsetmessages: + msg395956
2021-06-16 19:13:54mark.dickinsonsetmessages: + msg395955
2021-06-16 17:44:08miss-islingtonsetpull_requests: + pull_request25346
2021-06-16 17:44:02miss-islingtonsetnosy: + miss-islington
pull_requests: + pull_request25345
2021-06-16 17:43:57mark.dickinsonsetmessages: + msg395952
2021-06-15 19:04:42mark.dickinsonsetkeywords: + patch
stage: patch review
pull_requests: + pull_request25329
2021-06-15 18:14:40mark.dickinsonsetmessages: + msg395889
2021-06-15 18:05:19mark.dickinsonsetnosy: + mark.dickinson
messages: + msg395888
2021-06-15 12:42:29ksurmacreate