GeezerVison is showing github.com — Docs build error with Sphinx 3.0 due to invalid C declaration · Issue #84385 · python/cpython
Docs build error with Sphinx 3.0 due to invalid C declaration #84385Description
| 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) #19443bpo-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) #21147bpo-40204: Allow pre-Sphinx 3 syntax in the doc #21844bpo-40204, doc: Fix syntax of C variables #21846bpo-40204: Fix duplicates in the documentation #21857bpo-40204: Fix Sphinx sytanx in howto/instrumentation.rst #21858bpo-40204: Add :noindex: in the documentation #21859bpo-40204: Fix reference to terms in the doc #21865bpo-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) #21928bpo-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'] Activitytirkarthi commented on Apr 6, 2020 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 :
|
$(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 commented on Apr 6, 2020 serhiy-storchaka commented on Apr 6, 2020 tirkarthi commented on Apr 7, 2020 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 commented on Apr 8, 2020
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 <[email protected]>
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 commented on Apr 8, 2020
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 commented on Apr 8, 2020 vstinner commented on Aug 13, 2020 vstinner commented on Aug 14, 2020 vstinner commented on Aug 17, 2020 vstinner commented on Aug 17, 2020 I'm now able to build the Python documentation with Sphinx 3.2.1 without modifying the Doc/Makefile, so using -W option (treat warnings as errors): there are no more Sphinx 3 warnings.
When Sphinx 3 will be more widely available (ex: in Linux distributions), we will be able to consider removing c_allow_pre_v3=True and c_warn_on_allowed_pre_v3=False in doc/conf.py. For that, we should update the documentation to use the Sphinx 3 syntax, see PR 19397 written by Jakob Lykke Andersen.
For now, I prefer to keep Sphinx 2 support and so keep Sphinx 2 syntax in the C domain, since it allows supporting Sphinx 2 and Sphinx 3. vstinner commented on Aug 19, 2020 vstinner commented on Aug 20, 2020 vstinner commented on Aug 20, 2020 I merged my changes to add Sphinx 3.2 and newer support into 3.8, 3.9 and master branches.
I close the issue.
Sadly, it seems like it's not possible to keep Sphinx 2 support if we add Sphinx 3.0 and Sphinx 3.1 support. For now, only Sphinx 2 and Sphinx 3.2+ are supported: 3.0 and 3.1 are not supported. vstinner commented on Sep 2, 2020
MetadataMetadataDevelopmentNo branches or pull requestsIssue actions
|