Docs build error with Sphinx 3.0 due to invalid C declaration

[tirkarthi]

BPO	40204
Nosy	@birkenfeld, @rhettinger, @terryjreedy, @doko42, @vstinner, @benjaminp, @ned-deily, @ezio-melotti, @merwok, @skrah, @serhiy-storchaka, @willingc, @JulienPalard, @miss-islington, @tirkarthi, @m-aciek
PRs	bpo-40204: Update documentation formatting for Sphinx 3.0 #19397 [3.8] bpo-40204: Pin Sphinx version to 1.8.2 in Doc/Makefile #19442 [3.7] bpo-40204: Pin Sphinx version to 1.8.2 in Doc/Makefile (GH-19442) #19443 bpo-40204: Pin Sphinx version to 2.3.1 in Doc/Makefile. #21141 [3.9] bpo-40204: Pin Sphinx version to 2.3.1 in Doc/Makefile. (GH-21141) #21146 [3.8] bpo-40204: Pin Sphinx version to 2.3.1 in Doc/Makefile. (GH-21141) #21147 bpo-40204: Allow pre-Sphinx 3 syntax in the doc #21844 bpo-40204, doc: Fix syntax of C variables #21846 bpo-40204: Fix duplicates in the documentation #21857 bpo-40204: Fix Sphinx sytanx in howto/instrumentation.rst #21858 bpo-40204: Add :noindex: in the documentation #21859 bpo-40204: Fix reference to terms in the doc #21865 bpo-40204: Fix duplicated productionlist names in the doc #21900 [3.9] bpo-40204: Allow pre-Sphinx 3 syntax in the doc (GH-21844) #21901 [3.8] bpo-40204: Allow pre-Sphinx 3 syntax in the doc (GH-21844) (GH-21901) #21924 [3.8] bpo-40204: Allow pre-Sphinx 3 syntax in the doc (GH-21844) (GH-21901) #21928 bpo-40204: Update Sphinx to version 3.2.1 in Doc/Makefile #22043

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2020-08-20.11:33:09.064>
created_at = <Date 2020-04-06.14:32:48.165>
labels = ['type-bug', '3.8', '3.9', '3.10', 'docs']
title = 'Docs build error with Sphinx 3.0 due to invalid C declaration'
updated_at = <Date 2020-09-02.10:29:35.521>
user = 'https://github.com/tirkarthi'

bugs.python.org fields:

activity = <Date 2020-09-02.10:29:35.521>
actor = 'vstinner'
assignee = 'docs@python'
closed = True
closed_date = <Date 2020-08-20.11:33:09.064>
closer = 'vstinner'
components = ['Documentation']
creation = <Date 2020-04-06.14:32:48.165>
creator = 'xtreak'
dependencies = []
files = []
hgrepos = []
issue_num = 40204
keywords = ['patch']
message_count = 42.0
messages = ['365858', '365872', '365876', '365895', '366021', '366022', '366023', '366082', '366090', '366091', '366096', '366097', '366172', '371790', '372262', '372265', '372271', '372292', '372347', '372348', '372353', '372698', '372701', '372702', '372704', '372858', '373083', '374736', '375254', '375281', '375320', '375321', '375335', '375341', '375343', '375392', '375527', '375529', '375661', '375703', '375704', '376223']
nosy_count = 18.0
nosy_names = ['georg.brandl', 'rhettinger', 'terry.reedy', 'doko', 'vstinner', 'benjamin.peterson', 'ned.deily', 'ezio.melotti', 'eric.araujo', 'skrah', 'docs@python', 'python-dev', 'serhiy.storchaka', 'willingc', 'mdk', 'miss-islington', 'xtreak', 'Maciej Olko']
pr_nums = ['19397', '19442', '19443', '21141', '21146', '21147', '21844', '21846', '21857', '21858', '21859', '21865', '21900', '21901', '21924', '21928', '22043']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue40204'
versions = ['Python 3.8', 'Python 3.9', 'Python 3.10']

[tirkarthi]

The following error is caused in Docs build for a 3.8 backport since sphinx is ran with warnings. Sphinx released 3.0 on April 6. The last successful build on master uses Sphinx 2.2.0 [0]. My guess is sphinx new version possibly breaking the build on Python 3.8 where it's not pinned to use 2.2.0 pulling the latest version. The changelog for Sphinx has below note :

https://www.sphinx-doc.org/en/master/changes.html#release-3-0-0-released-apr-06-2020

The C domain has been rewritten, with additional directives and roles. The existing ones are now more strict, resulting in new warnings.

Python 3.8 and Python 3.7 doesn't have Sphinx pinned to 2.2.0 while master does.

Python 3.8 Docs makefile :

cpython/Doc/Makefile

Line 146 in f7b0259

$(VENVDIR)/bin/python3 -m pip install -U Sphinx blurb python-docs-theme

Failed build :

https://github.com/python/cpython/pull/19388/checks?check_run_id=563053793#step:7:46

Error :

Warning, treated as error:
/home/runner/work/cpython/cpython/Doc/c-api/buffer.rst:92:Error in declarator or parameters
Invalid C declaration: Expected identifier in nested name. [error at 5]
void \*buf
-----^
Makefile:49: recipe for target 'build' failed
make[1]: *** [build] Error 2

[0] https://github.com/python/cpython/runs/564123625#step:6:24

[vstinner]

It sounds dangerous to not pin the Sphinx version in our CI :-/ Another issue caused by CI configuration stored at the same place than the code:
https://mail.python.org/archives/list/python-committers@python.org/thread/WEU5CQKIA4LIHWHT53YA7HHNUY5H2FUT/

[serhiy-storchaka]

Maybe copy the code for deprecated and removed features to Doc/tools/extensions?

[tirkarthi]

The sphinx version is not pinned in 3.7, 3.6, 3.5 and 2.7 branches too for Doc/Makefile that can cause error on someone trying it out locally. They are pinned in .travis.yml and .azure-pipelines configurations.

[vstinner]

Python 3.8 and Python 3.7 doesn't have Sphinx pinned to 2.2.0 while master does.

In 3.8, .azure-pipelines/docs-steps.yml contains:

• script: python -m pip install sphinx==1.8.2 blurb python-docs-theme

and .travis.yml contains:

• python -m pip install sphinx==1.8.2 blurb python-docs-theme

For example, the Sphinx version was changed from 1.8.1 to 1.8.2 in the CI configuration by:

commit 7f4ba4a
Author: Julien Palard <julien@palard.fr>
Date: Sat Nov 24 11:35:21 2018 +0100

Doc: Bump sphinx. (GH-10676)

--

I guess that you're talking about Doc/Makefile which uses "Sphinx" in 3.8 but "Sphinx==2.2.0" in master. Code in 3.8:

venv:
$(PYTHON) -m venv $(VENVDIR)
$(VENVDIR)/bin/python3 -m pip install -U pip setuptools
$(VENVDIR)/bin/python3 -m pip install -U Sphinx blurb python-docs-theme
@echo "The venv has been created in the $(VENVDIR) directory"

[vstinner]

I guess that you're talking about Doc/Makefile which uses "Sphinx" in 3.8 but "Sphinx==2.2.0" in master.

I wrote PR 19442 to pin Sphinx version to 1.8.2 in Doc/Makefile.

[vstinner]

New changeset 37a257c by Victor Stinner in branch '3.8':
bpo-40204: Pin Sphinx version to 1.8.2 in Doc/Makefile (GH-19442)
37a257c