Revision as of 10:09, 1 June 2021

Update Sphinx to 4.0.x

Summary

The version 4.0.x of Sphinx, popular Python documentation generator and framework, has been released in May 2021. It brings many bug fixes, new features including breaking changes and removes long deprecated functions.

Package maintainers whose packages will stop building with the Sphinx 4.0.x have these options:

they switch to Sphinx 4.0.x for building their documentation,
they stop building documentation,
they create compat package to extend the lifespan of Sphinx 3.x features. Python-maint team can assist with creating the compat package, however we don't like this solution and discourage from doing so.

Owner

Name: Karolina Surma
Email: ksurma@redhat.com

Current status

Targeted release: Fedora Linux 35
Last updated: 2021-06-01
FESCo issue: <will be assigned by the Wrangler>
Tracker bug: <will be assigned by the Wrangler>
Release notes tracker: <will be assigned by the Wrangler>

Detailed Description

Many Fedora packages build-depend on python-sphinx, a popular documentation framework. It was assessed that around 60 packages stop building with the Sphinx 4.0.2. The common reasons for failures are:

they use long-deprecated functions which have been removed in Sphinx 4.0.2,
they depend on components which explicitly require older Sphinx versions.

The change affects these packages (bear in mind, the list may not be complete - some packages which don't build because of the other issues, may be affected also with this change):

As said in the summary, packages will either switch to Sphinx 4.0.x or stop building the docs. Change owners can provide guidance and help, yet they cannot be expected to fix all the packages.

Benefit to Fedora

Fedora is the leading environment for Python development and will include the newest and greatest Sphinx for users and packagers. They will benefit from its newest functions to build better documentation.

Scope

Proposal owners: update python-sphinx to 4.0.x, provide help

Other developers: the update of affected packages can be tested using copr repository where the testing version of Sphinx 4.0.2 has been built.

Release engineering: N/A #Releng issue number

Policies and guidelines: N/A (not needed for this Change)

Trademark approval: N/A (not needed for this Change)

Alignment with Objectives: N/A

Upgrade/compatibility impact

There is a clean upgrade path from current version to 4.0.x. Fedora users using RPM-packaged Sphinx will use Sphinx 4.0.x by default.

How To Test

The update of affected packages can be tested using copr repository where the proposed version of Sphinx 4.0.2 has been built.

User Experience

Already covered by sections above.

Dependencies

Already covered in Detailed Description

Contingency Plan

Contingency mechanism: (What to do? Who will do it?) N/A (not a System Wide Change)
Contingency deadline: N/A (not a System Wide Change)
Blocks release? No

Documentation

Sphinx changelog This page is the documentation for Fedora impact.

Release Notes

N/A

@@ Line 1: / Line 1: @@
-= [DRAFT] Update Sphinx to 4.0.x =
+= Update Sphinx to 4.0.x =
 == Summary ==
@@ Line 52: / Line 52: @@
 * they depend on components which explicitly require older Sphinx versions.
-The change affects these packages [here comes the list]
+The change affects these packages (bear in mind, the list may not be complete - some packages which don't build because of the other issues, may be affected also with this change):
+* [https://src.fedoraproject.org/rpms/ansible ansible]
+* [https://src.fedoraproject.org/rpms/ara ara]
+* [https://src.fedoraproject.org/rpms/arbor arbor]
+* [https://src.fedoraproject.org/rpms/borgbackup borgbackup]
+* [https://src.fedoraproject.org/rpms/botan botan]
+* [https://src.fedoraproject.org/rpms/buildstream buildstream]
+* [https://src.fedoraproject.org/rpms/condor condor]
+* [https://src.fedoraproject.org/rpms/copr-keygen copr-keygen]
+* [https://src.fedoraproject.org/rpms/extra-cmake-modules extra-cmake-modules]
+* [https://src.fedoraproject.org/rpms/gcc gcc]
+* [https://src.fedoraproject.org/rpms/ghc ghc]
+* [https://src.fedoraproject.org/rpms/gtksourceview4 gtksourceview4]
+* [https://src.fedoraproject.org/rpms/kea kea]
+* [https://src.fedoraproject.org/rpms/krb5 krb5]
+* [https://src.fedoraproject.org/rpms/libcomps libcomps]
+* [https://src.fedoraproject.org/rpms/libgpuarray libgpuarray]
+* [https://src.fedoraproject.org/rpms/llvm llvm]
+* [https://src.fedoraproject.org/rpms/Mayavi Mayavi]
+* [https://src.fedoraproject.org/rpms/paraview paraview]
+* [https://src.fedoraproject.org/rpms/php-opencloud-openstack php-opencloud-openstack]
+* [https://src.fedoraproject.org/rpms/pipenv pipenv]
+* [https://src.fedoraproject.org/rpms/pki-core pki-core]
+* [https://src.fedoraproject.org/rpms/py4j py4j]
+* [https://src.fedoraproject.org/rpms/python3-docs python3-docs]
+* [https://src.fedoraproject.org/rpms/python-anyio python-anyio]
+* [https://src.fedoraproject.org/rpms/python-breathe python-breathe]
+* [https://src.fedoraproject.org/rpms/python-BTrees python-BTrees]
+* [https://src.fedoraproject.org/rpms/python-diff-cover python-diff-cover]
+* [https://src.fedoraproject.org/rpms/python-djvulibre python-djvulibre]
+* [https://src.fedoraproject.org/rpms/python-f5-sdk python-f5-sdk]
+* [https://src.fedoraproject.org/rpms/python-flit python-flit]
+* [https://src.fedoraproject.org/rpms/python-glue python-glue]
+* [https://src.fedoraproject.org/rpms/python-h2 python-h2]
+* [https://src.fedoraproject.org/rpms/python-libpysal python-libpysal]
+* [https://src.fedoraproject.org/rpms/python-listparser python-listparser]
+* [https://src.fedoraproject.org/rpms/python-novaclient python-novaclient]
+* [https://src.fedoraproject.org/rpms/python-openstackclient python-openstackclient]
+* [https://src.fedoraproject.org/rpms/python-patsy python-patsy]
+* [https://src.fedoraproject.org/rpms/python-persistent python-persistent]
+* [https://src.fedoraproject.org/rpms/python-pip python-pip]
+* [https://src.fedoraproject.org/rpms/python-pkginfo python-pkginfo]
+* [https://src.fedoraproject.org/rpms/python-pycryptodomex python-pycryptodomex]
+* [https://src.fedoraproject.org/rpms/python-pynetdicom python-pynetdicom]
+* [https://src.fedoraproject.org/rpms/python-pysam python-pysam]
+* [https://src.fedoraproject.org/rpms/python-pyswarms python-pyswarms]
+* [https://src.fedoraproject.org/rpms/python-rjsmin python-rjsmin]
+* [https://src.fedoraproject.org/rpms/python-ruffus python-ruffus]
+* [https://src.fedoraproject.org/rpms/python-sphinxcontrib-asyncio python-sphinxcontrib-asyncio]
+* [https://src.fedoraproject.org/rpms/python-sphinxcontrib-trio python-sphinxcontrib-trio]
+* [https://src.fedoraproject.org/rpms/python-sphinx-notfound-page python-sphinx-notfound-page]
+* [https://src.fedoraproject.org/rpms/python-texext python-texext]
+* [https://src.fedoraproject.org/rpms/python-txtorcon python-txtorcon]
+* [https://src.fedoraproject.org/rpms/python-whoosh python-whoosh]
+* [https://src.fedoraproject.org/rpms/python-zarr python-zarr]
+* [https://src.fedoraproject.org/rpms/rebase-helper rebase-helper]
+* [https://src.fedoraproject.org/rpms/tortoisehg tortoisehg]
+* [https://src.fedoraproject.org/rpms/waiverdb waiverdb]
+* [https://src.fedoraproject.org/rpms/xeus xeus]
+* [https://src.fedoraproject.org/rpms/xtl xtl]
+As said in the summary, packages will either switch to Sphinx 4.0.x or stop building the docs. Change owners can provide guidance and help, yet they cannot be expected to fix all the packages.
 == Benefit to Fedora ==
-Fedora is the leading environment for Python development and will include the newest and greatest Sphinx for users and packagers.
+Fedora is the leading environment for Python development and will include the newest and greatest Sphinx for users and packagers. They will benefit from its newest functions to build better documentation.
 <!-- What is the benefit to the distribution?  Will the software we generate be improved? How will the process of creating Fedora releases be improved?
@@ Line 86: / Line 147: @@
       https://fedoraproject.org/wiki/Changes/perl5.26 (major upgrade to a popular software stack, visible to users of that stack)
 -->
 == Scope ==
-* Proposal owners:
+* Proposal owners: update python-sphinx to 4.0.x, provide help
 <!-- What work do the feature owners have to accomplish to complete the feature in time for release?  Is it a large change affecting many parts of the distribution or is it a very isolated change? What are those changes?-->
-* Other developers: <!-- REQUIRED FOR SYSTEM WIDE CHANGES -->
+* Other developers: the update of affected packages can be tested using [https://copr.fedorainfracloud.org/coprs/ksurma/pygments-2.9.0/ copr repository] where the testing version of Sphinx 4.0.2 has been built.
+<!-- REQUIRED FOR SYSTEM WIDE CHANGES -->
 <!-- What work do other developers have to accomplish to complete the feature in time for release?  Is it a large change affecting many parts of the distribution or is it a very isolated change? What are those changes?-->
-* Release engineering: [https://pagure.io/releng/issues #Releng issue number] <!-- REQUIRED FOR SYSTEM WIDE CHANGES -->
+* Release engineering: N/A [https://pagure.io/releng/issues #Releng issue number] <!-- REQUIRED FOR SYSTEM WIDE CHANGES -->
 <!-- Does this feature require coordination with release engineering (e.g. changes to installer image generation or update package delivery)?  Is a mass rebuild required?  include a link to the releng issue.
 The issue is required to be filed prior to feature submission, to ensure that someone is on board to do any process development work and testing and that all changes make it into the pipeline; a bullet point in a change is not sufficient communication -->
@@ Line 104: / Line 165: @@
 <!-- If your Change may require trademark approval (for example, if it is a new Spin), file a ticket ( https://pagure.io/Fedora-Council/tickets/issues ) requesting trademark approval from the Fedora Council. This approval will be done via the Council's consensus-based process. -->
-* Alignment with Objectives:
+* Alignment with Objectives: N/A
 <!-- Does your proposal align with the current Fedora Objectives: https://docs.fedoraproject.org/en-US/project/objectives/ ? It's okay if it doesn't, but it's something to consider -->
 == Upgrade/compatibility impact ==
+There is a clean upgrade path from current version to 4.0.x.
+Fedora users using RPM-packaged Sphinx will use Sphinx 4.0.x by default.
 <!-- What happens to systems that have had a previous versions of Fedora installed and are updated to the version containing this change? Will anything require manual configuration or data migration? Will any existing functionality be no longer supported? -->
 <!-- REQUIRED FOR SYSTEM WIDE CHANGES -->
 == How To Test ==
@@ Line 130: / Line 192: @@
 <!-- REQUIRED FOR SYSTEM WIDE CHANGES -->
+The update of affected packages can be tested using [https://copr.fedorainfracloud.org/coprs/ksurma/pygments-2.9.0/ copr repository] where the proposed version of Sphinx 4.0.2 has been built.
 == User Experience ==
@@ Line 142: / Line 205: @@
   - Green has been scientifically proven to be the most relaxing color. The move to a default background color of green with green text will result in Fedora users being the most relaxed users of any operating system.
 -->
+Already covered by sections above.
 == Dependencies ==
@@ Line 147: / Line 211: @@
 <!-- REQUIRED FOR SYSTEM WIDE CHANGES -->
+Already covered in [https://fedoraproject.org/w/index.php?title=Changes/Sphinx4&action=submit#Detailed_Description Detailed Description]
 == Contingency Plan ==
@@ Line 156: / Line 220: @@
 * Contingency deadline: N/A (not a System Wide Change)  <!-- REQUIRED FOR SYSTEM WIDE CHANGES -->
 <!-- Does finishing this feature block the release, or can we ship with the feature in incomplete state? -->
-* Blocks release? N/A (not a System Wide Change), Yes/No <!-- REQUIRED FOR SYSTEM WIDE CHANGES -->
+* Blocks release? No
 == Documentation ==
@@ Line 163: / Line 226: @@
 <!-- REQUIRED FOR SYSTEM WIDE CHANGES -->
-N/A (not a System Wide Change)
+[https://www.sphinx-doc.org/en/master/changes.html Sphinx changelog]
+This page is the documentation for Fedora impact.
 == Release Notes ==
@@ Line 171: / Line 235: @@
 Release Notes are not required for initial draft of the Change Proposal but has to be completed by the Change Freeze.
 -->
+N/A

Search

Changes/Sphinx4: Difference between revisions