Docutils Building Wheels

Abstract

This document documents trials to build python wheels from Docutils. Once it is finished it might be driven into distribution or release documentation.

Requests

There is feature request 43 : Make setup.py build wheels.

Just add this to setup.cfg:

[bdist_wheel] universal = 1

and bugs275 : Upload wheels to pypi

Currently docutils does not publish any wheels on pypi. Wheels make docutils faster to install (no need to run setup.py, which for a large number of packages can take some time), and is no more difficult than uploading an sdist (see https://packaging.python.org/en/latest/distributing.html#wheels for instructions).

Logbook

1. Add [bdist_wheel] universal = 0 to setup.cfg.

2. Run python setup.py bdist_wheel:

   error: invalid command 'bdist_wheel'

3. setuptools is too old. Install the new one by wheel or source or pip or easy...

4. try wheel ... first get wheel tar.gz and unpack.

5. try

   python2.7 wheel-0.24.0/wheel install setuptools-15.0-py2.py3-none-any.whl

   no error. But still error: invalid command 'bdist_wheel':

   $ python2.7 setup.py --version
   0.12

   Did wheel install ? If no, why no error, if yes in which place ?

Logbook: with setuptools branch

gitpull/setuptools sandbox branch introduces setuptools in setup.py.

As of 2015-04-16: Not working yet, import docutils will raise an ImportError. Need to get packages detected correctly.

Install:

$ svn checkout svn://svn.code.sf.net/p/docutils/code/trunk/sandbox/gitpull/setuptools docutils-setuptools
$ cd setuptools
# create a virtualenv (however you like)
$ pip install -e .

This includes support for generate python setup.py bdist_wheel:

$ python setup.py bdist_wheel
running bdist_wheel
running build
running build_scripts
installing to build/bdist.linux-x86_64/wheel
running install
running install_egg_info
running egg_info
writing docutils.egg-info/PKG-INFO
writing top-level names to docutils.egg-info/top_level.txt
writing dependency_links to docutils.egg-info/dependency_links.txt
reading manifest file 'docutils.egg-info/SOURCES.txt'
reading manifest template 'MANIFEST.in'
warning: no files found matching 'MANIFEST'
warning: no files found matching '*' under directory 'extras'
warning: no previously-included files matching '.cvsignore' found under directory '*'
warning: no previously-included files matching '*~' found under directory '*'
warning: no previously-included files matching '.DS_Store' found under directory '*'
writing manifest file 'docutils.egg-info/SOURCES.txt'
Copying docutils.egg-info to build/bdist.linux-x86_64/wheel/docutils-0.13.data/purelib/docutils-0.13-py2.7.egg-info
running install_scripts
creating build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts
copying build/scripts-2.7/rst2pseudoxml.py -> build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts
copying build/scripts-2.7/rst2man.py -> build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts
copying build/scripts-2.7/rst2odt.py -> build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts
copying build/scripts-2.7/rst2latex.py -> build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts
copying build/scripts-2.7/rstpep2html.py -> build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts
copying build/scripts-2.7/rst2s5.py -> build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts
copying build/scripts-2.7/rst2odt_prepstyles.py -> build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts
copying build/scripts-2.7/rst2html.py -> build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts
copying build/scripts-2.7/rst2html5.py -> build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts
copying build/scripts-2.7/rst2xml.py -> build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts
copying build/scripts-2.7/rst2xetex.py -> build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts
changing mode of build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts/rst2pseudoxml.py to 755
changing mode of build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts/rst2man.py to 755
changing mode of build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts/rst2odt.py to 755
changing mode of build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts/rst2latex.py to 755
changing mode of build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts/rstpep2html.py to 755
changing mode of build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts/rst2s5.py to 755
changing mode of build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts/rst2odt_prepstyles.py to 755
changing mode of build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts/rst2html.py to 755
changing mode of build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts/rst2html5.py to 755
changing mode of build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts/rst2xml.py to 755
changing mode of build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts/rst2xetex.py to 755
creating build/bdist.linux-x86_64/wheel/docutils-0.13.dist-info/WHEEL

Installation:

# create a fresh virtualenv
$ pip install -U dist/docutils-0.13-cp27-none-linux_x86_64.whl
Processing ./dist/docutils-0.13-cp27-none-linux_x86_64.whl
Installing collected packages: docutils
Found existing installation: docutils 0.13
Uninstalling docutils-0.13:
Successfully uninstalled docutils-0.13
Successfully installed docutils-0.13

Logbook with "pip"

Docutils' "setup.py" imports from the stdlib's "distutils" module instead of the 3rd party "setuptools". "distutils" cannot build wheels. [1]

OTOH, pip internally uses "setuptools" instead of "distutils". This way, it can generate wheels without changes to "setup.py".

1. Install "pip" and "wheels"

   Under Debian Gnu/Linux: aptitude install python-pip python3-pip

2. In the repository root directory, run

   #> pip wheel ./docutils/
   Unpacking ./docutils
     Running setup.py (path:/tmp/pip-Ym9hKL-build/setup.py) egg_info for package from file:///[...]docutils-svn/docutils
   
       warning: no previously-included files matching '.DS_Store' found under directory '*'
   Building wheels for collected packages: docutils
     Running setup.py bdist_wheel for docutils
     Destination directory: /home/milde/Code/Python/docutils-svn/wheelhouse
   Successfully built docutils
   Cleaning up...

3. There is a "pure Python" wheel under wheelhouse/docutils-0.13-py2-none-any.whl

4. Repeat with:

   #> pip3 wheel ./docutils/

   to get wheelhouse/docutils-0.13-py3-none-any.whl

You can also generate wheels for Docutils 0.12 with pip wheel docutils and pip3 wheel docutils. The 0.12 archive is downloaded from PIP and re-packed as wheel. With "pip3" this includes the 2to3 conversion.

Summary:

With the "pip" utility, it is possible to generate wheels for Python 2 and 3 for both, the released and the repository version of Docutils without changes to the code base.

The generated wheel can be installed. Installing the Py3k version happens "instantaneously".