Re: Sphinx pre v3 -- removing support

[Mauro Carvalho Chehab <mchehab@kernel.org>]

Em Fri, 3 Jun 2022 15:27:18 +0000
Adam Turner <aaturnerpython@outlook.com> escreveu:

> >> From Sphinx's perspective, we'd like to remove long-deprecated code.
> >> What is a good solution here for both sides? The intertial option is
> >> for us to delay the deprecation by another major version (removal is
> >> currently scheduled for Sphinx 6 (2023-05), and we are currently 
> >> releasing a major version every May.  
> 
> > So, can we assume that there won't be any backward-incompatible
> > behavior changes in Sphinx due to the removal of those long-deprecated
> > code?  
> 
> I'm referring to removing support for the "c_allow_pre_v3", 
> "c_warn_on_allowed_pre_v3", configuration options [1]_, and the 
> associated support for still parsing the pre v3 syntax in the C 
> domain [2]_. This means that pre v3 syntax in reStructuredText files
> would not work with Sphinx 6 onwards.
> 
> > Or do you mean that after the release of Sphinx 6, pre v3 Sphinx
> > will be removed in the PyPI repository?  
> 
> No releases will be removed from PyPI, but if pre v3 syntax is still
> used, Sphinx 6.0 would fail to properly parse it.

Adam,

Despite the performance issues with Sphinx > 2.x.x, there is another
reason why the default is to use 2.4.4 version. Currently, building
the docs with any version newer than that will cause 11 false-positives
warnings:

	    Documentation/driver-api/usb/usb:164: ./drivers/usb/core/message.c:967: WARNING: Duplicate C declaration, also defined at driver-api/usb/gadget:783.
Declaration is '.. c:function:: int usb_string (struct usb_device *dev, int index, char *buf, size_t size)'.
    Documentation/driver-api/usb/usb.rst:967: WARNING: Duplicate C declaration, also defined at driver-api/usb/gadget:783.
Declaration is '.. c:struct:: usb_string'.
    Documentation/driver-api/miscellaneous:48: ./drivers/pwm/core.c:599: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous:240.
Declaration is '.. c:function:: int pwm_capture (struct pwm_device *pwm, struct pwm_capture *result, unsigned long timeout)'.
    Documentation/driver-api/surface_aggregator/client-api:25: ./drivers/platform/surface/aggregator/controller.c:1689: WARNING: Duplicate C declaration, also defined at driver-api/surface_aggregator/client-api:105.
Declaration is '.. c:function:: int ssam_request_sync (struct ssam_controller *ctrl, const struct ssam_request *spec, struct ssam_response *rsp)'.
    Documentation/driver-api/80211/mac80211:109: ./include/net/mac80211.h:4933: WARNING: Duplicate C declaration, also defined at driver-api/80211/mac80211:1041.
Declaration is '.. c:function:: void ieee80211_tx_status (struct ieee80211_hw *hw, struct sk_buff *skb)'.
    Documentation/gpu/amdgpu/driver-core:163: ./drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c:735: WARNING: Duplicate C declaration, also defined at gpu/amdgpu/driver-core:93.
Declaration is '.. c:function:: void amdgpu_vm_tlb_seq_cb (struct dma_fence *fence, struct dma_fence_cb *cb)'.
    Documentation/gpu/drm-kms:360: ./drivers/gpu/drm/drm_fourcc.c:298: WARNING: Duplicate C declaration, also defined at gpu/drm-kms:36.
Declaration is '.. c:function:: const struct drm_format_info * drm_format_info (u32 format)'.
    Documentation/gpu/drm-kms:459: ./drivers/gpu/drm/drm_modeset_lock.c:392: WARNING: Duplicate C declaration, also defined at gpu/drm-kms:49.
Declaration is '.. c:function:: int drm_modeset_lock (struct drm_modeset_lock *lock, struct drm_modeset_acquire_ctx *ctx)'.
    Documentation/gpu/drm-uapi:357: ./drivers/gpu/drm/drm_ioctl.c:917: WARNING: Duplicate C declaration, also defined at gpu/drm-uapi:70.
Declaration is '.. c:function:: bool drm_ioctl_flags (unsigned int nr, unsigned int *flags)'.
    Documentation/gpu/rfc/i915_scheduler:138: ./include/uapi/drm/i915_drm.h:3: WARNING: Duplicate C declaration, also defined at gpu/driver-uapi:2101.
Declaration is '.. c:struct:: i915_context_engines_parallel_submit'.
    Documentation/gpu/rfc/i915_scheduler.rst:3: WARNING: Duplicate C declaration, also defined at gpu/driver-uapi:2101.
Declaration is '.. c:struct:: i915_context_engines_parallel_submit'.

Basically, on 11 places inside the Kernel we use the same name for
functions and for struct (or enum), as this is perfectly fine on C.

Yet, even having different tags at the C domain after Sphinx 3.x, it
still doesn't place them on separate namespaces. Those are all caused
by this bug, whose fixes are yet to be merged:

	https://github.com/sphinx-doc/sphinx/pull/8313

Is this planned to be solved during Sphinx 5.x development cycle?

Regards,
Mauro