Update Sphinx to version 2 and drop Python 2 support from Sphinx
Summary
The version 2.0.x of Sphinx, popular Python documentation generator and framework, is expected to be released in early 2019. It drops support for Python 2. As part of Finalizing Fedora's Switch to Python 3, we update python-sphinx
to 2.0.x and we drop python2-sphinx
and related packages from Fedora 31 and further.
Package maintainers using Sphinx on Python 2 have three options:
- they stop using Python 2 entirely (preferred), dropping their python2 subpackages if not dependent upon by other packages,
- they switch to Sphinx on Python 3 for building their documentation,
- they stop building documentation.
Packages that use Sphinx on Python 2 at runtime are Sphinx extensions, themes etc. and will be removed together with python2-sphinx
.
Owner
- Name: Miro Hrončok as the lead Python 2 deletionist
- Name: Charalampos Stratakis as the
python-sphinx
maintainer - Email: python-maint@redhat.com
- Release notes owner:
Current status
- Targeted release: Fedora 31
- Last updated: 2019-03-06
- Tracker bug: #1685211
- Release notes tracker: #306
Detailed Description
See live (or several days old) information of Python dependents of python2-sphinx
at the Python 2 Dropping Database.
We will remove the following (sub)packages:
python2-sphinx
https://src.fedoraproject.org/rpms/python-sphinx/pull-request/8python2-catkin-sphinx
https://src.fedoraproject.org/rpms/python-catkin-sphinx/pull-request/2python2-numpydoc
https://src.fedoraproject.org/rpms/python-numpydoc/pull-request/1python2-openstack-doc-tools
(already removed in F30)python2-openstackdocstheme
(already removed in F30)python2-snowballstemmer
https://src.fedoraproject.org/rpms/python-snowballstemmer/pull-request/1python2-sphinx-intl
https://src.fedoraproject.org/rpms/python-sphinx-intl/pull-request/3python2-sphinx-theme-alabaster
https://src.fedoraproject.org/rpms/python-sphinx-theme-alabaster/pull-request/2python2-sphinx_rtd_theme
https://src.fedoraproject.org/rpms/python-sphinx_rtd_theme/pull-request/1python2-sphinxcontrib-httpdomain
https://src.fedoraproject.org/rpms/python-sphinxcontrib-httpdomain/pull-request/2python2-sphinxcontrib-websupport
https://src.fedoraproject.org/rpms/python-sphinxcontrib-websupport/pull-request/3sphinx-webtools
https://src.fedoraproject.org/rpms/sphinx-webtools/pull-request/2trac-sphinx-plugin
https://src.fedoraproject.org/rpms/trac-sphinx-plugin/pull-request/2
The following (source) packages currently (2019-02-06) BuildRequire any of the above and will need to be modified to stop BuildRequiring them:
alot
autotest-framework
beaker
BEDTools
bpython
bro
bugzilla
bzr
catkin
datagrepper
extra-cmake-modules
fedmsg
gdeploy
gnuradio
h5py
idris
libmypaint
mirrorbrain
mod_wsgi
moksha
mp
nextcloud-client
nordugrid-arc-nagios-plugins
notmuch
offlineimap
owncloud-client
paraview
percona-xtrabackup
petsc
python-arc
python-bashate
python-bloom
python-Bottleneck
python-breathe
python-case
python-catkin_pkg
python-cliapp
python-cloudservers
python-debtcollector
python-dulwich
python-eventlet
python-factory-boy
python-fedora
python-feedparser
python-flask
python-flask-httpauth
python-funcsigs
python-futurist
python-gabbi
python-genmsg
python-genpy
python-gunicorn
python-hacking
python-hardware
python-hl7
python-htmlmin
python-jenkins-job-builder
python-jsonpath-rw-ext
python-kafka
python-kazoo
python-kitchen
python-larch
python-mpd2
python-mpmath
python-netaddr
python-ngram
python-nose_fixes
python-novaclient
python-nss
python-numpydoc
python-olefile
python-openstackdocstheme
python-openstack-doc-tools
python-oslo-config
python-oslo-serialization
python-oslo-utils
python-osrf-pycommon
python-os-service-types
python-parsley
python-pathlib
python-pbr
python-pika
python-pillow
python-pint
python-plaster
python-pwntools
python-pycares
python-pygments
python-pyperclip
python-pypump
python-pyramid
python-reno
python-restauth-common
python-rosdep
python-rosdistro
python-rosinstall
python-rospkg
python-sane
python-scripttest
python-slixmpp
python-sphinx
python-sphinxcontrib-websupport
python-sphinx-intl
python-statsd
python-statsmodels
python-testtools
python-tracing
python-txaio
python-txsocksx
python-vcstools
python-webcolors
python-werkzeug
python-whoosh
python-wrapt
python-wsgi_intercept
python-wstool
python-yaql
python-zope-component
python-zope-schema
python2-django1.11
python2-docs
python2-matplotlib
scipy
seqan2
shiboken
sphinx-webtools
swift-lang
the-new-hotness
tortoisehg
tryton
tsung
umit
virtio-forwarder
ViTables
xapian-bindings
As said in the summary, packages will either switch to Python 3 Sphinx or stop building the docs. Change owners can provide guidance and help, yet they cannot be expected to fix all the packages.
The following tools will be switched to Python 3:
/usr/bin/sphinx-apidoc
/usr/bin/sphinx-autogen
/usr/bin/sphinx-build
/usr/bin/sphinx-quickstart
Their -3
and -3.X
suffixed counterparts will be kept as symbolic links for backwards compatibility.
Explicit conflicts with old python2-sphinx
will be added and python2-sphinx
will be obsoleted via fedora-obsolete-packages
.
Benefit to Fedora
Fedora is the leading environment for Python development and will include the newest and greatest Sphinx for users and packagers. The removal of Python 2 Sphinx will help in getting rid of a significant amount of Python 2 usage, as Fedora's long term plan is to get rid of this legacy interpreter. Python 2 is deprecated in Fedora and its upstream support ends on 2020-01-01, very early in the Fedora 31 life time.
Scope
- Proposal owners: remove above-mentioned packages as soon as possible, update
python-sphinx
to 2.0.0 or newer, provide guidance and help.
- Other developers: stop using
python2-sphinx
(list of affected packages in the description)
- Release engineering: #8100 (no Release Engineering impact is anticipated)
- List of deliverables: empty
- Policies and guidelines: none
- Trademark approval: not needed for this Change
Upgrade/compatibility impact
The new python3-sphinx
package will have to conflict with the old python2-sphinx
package because the unversioned executables will be moved from python2-sphinx
to python3-sphinx
. Proper obsoletes will be added to ensure a clean upgrade path.
Fedora users using RPM-packaged Sphinx will use Sphinx on Python 3 by default, as many would expect. Fedora users still needing to use Sphinx running on Python 2 will use Python virtual environment and pip.
How To Test
TBD
User Experience
Already covered by sections above.
Dependencies
Described by the sections above.
Contingency Plan
- Contingency mechanism: If absolutely needed, the change owners will add compatibility
python2-sphinx
package with Sphinx 1.8.x but they are not willing to maintain it, so they plan to orphan it soon after Fedora 31 is released. - Contingency deadline: any time before release
- Blocks release? No
- Blocks product? No
Documentation
This page is the documentation.
Release Notes
TBD.