From Fedora Project Wiki
(releng issue)
(Polishing the wordings a bit)
Line 35: Line 35:
 
* they stop building documentation.
 
* they stop building documentation.
  
Packages that use Sphinx on Python 2 on runtime are Sphinx extensions, themes etc. and will be removed together with {{package|python2-sphinx}}.
+
Packages that use Sphinx on Python 2 at runtime are Sphinx extensions, themes etc. and will be removed together with {{package|python2-sphinx}}.
  
 
== Owner ==
 
== Owner ==
Line 90: Line 90:
 
* {{package|trac-sphinx-plugin}}
 
* {{package|trac-sphinx-plugin}}
  
The following (source) packages currently (2019-02-06) BuildRequire any of the above and will need to be adapted to stop doing that:
+
The following (source) packages currently (2019-02-06) BuildRequire any of the above and will need to be modified to stop BuildRequiring them:
  
 
* {{package|alot}}
 
* {{package|alot}}
Line 229: Line 229:
  
 
As said in the summary, packages will either switch to Python 3 Sphinx or stop building the docs.
 
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 are not expected to do all the work here.
+
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:
 
The following tools will be switched to Python 3:
Line 270: Line 270:
 
-->
 
-->
  
Fedora is the leading environment for Python development and will include the newest and nicest 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.
The removal of Python 2 Sphinx will help getting rid of significant Python 2 usage, as Fedora long term plan is to get rid of this legacy interpreter. Python 2 is deprecated in Fedora and its upstream support ends at 2020-01-01, very early in the Fedora 31 life time.
+
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 ==
 
== Scope ==
* Proposal owners: remove packages as described above as soon as possible, update {{package|python-sphinx}} to 2.0.0 or newer, provide guidance and help.
+
* Proposal owners: remove above-mentioned packages as soon as possible, update {{package|python-sphinx}} to 2.0.0 or newer, provide guidance and 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?-->
 
<!-- 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: stop using {{package|python2-sphinx}} (list of packages in description) <!-- REQUIRED FOR SYSTEM WIDE CHANGES -->
+
* Other developers: stop using {{package|python2-sphinx}} (list of affected packages in the description) <!-- 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?-->
 
<!-- 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?-->
  
Line 298: Line 298:
 
The new {{package|python3-sphinx}} package will have to conflict with the old {{package|python2-sphinx}} package. Proper obsoletes will be added.
 
The new {{package|python3-sphinx}} package will have to conflict with the old {{package|python2-sphinx}} package. Proper obsoletes will be added.
  
Fedora users using RPM packaged Sphinx will use Sphinx on Python 3 by default, as many would expect.
+
Fedora users using RPM-packaged Sphinx will use Sphinx on Python 3 by default, as many would expect.
Fedora users still needing to use Python 2 and Sphinx will use Python virtual environment and pip.
+
Fedora users still needing to use Sphinx running on Python 2 will use Python virtual environment and pip.
  
 
== How To Test ==
 
== How To Test ==

Revision as of 16:58, 13 February 2019


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 Package-x-generic-16.pngpython-sphinx to 2.0.x and we drop Package-x-generic-16.pngpython2-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 Package-x-generic-16.pngpython2-sphinx.

Owner

Current status

  • Targeted release: Fedora 31
  • Last updated: 2019-02-13
  • Tracker bug: <will be assigned by the Wrangler>

Detailed Description

See live (or several days old) information of Python dependents of Package-x-generic-16.pngpython2-sphinx at the Python 2 Dropping Database.

We will remove the following (sub)packages:

The following (source) packages currently (2019-02-06) BuildRequire any of the above and will need to be modified to stop BuildRequiring them:

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.

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 Package-x-generic-16.pngpython-sphinx to 2.0.0 or newer, provide guidance and help.
  • Other developers: stop using Package-x-generic-16.pngpython2-sphinx (list of affected packages in the description)
  • Policies and guidelines: none
  • Trademark approval: not needed for this Change

Upgrade/compatibility impact

The new Package-x-generic-16.pngpython3-sphinx package will have to conflict with the old Package-x-generic-16.pngpython2-sphinx package. Proper obsoletes will be added.

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 Package-x-generic-16.pngpython2-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.