|
|
|
|
|
===========================
|
|
|
|
|
|
Docutils_ Building Wheels
|
|
|
|
|
|
===========================
|
|
|
|
|
|
|
|
|
|
|
|
:Authors: engelbert gruber; open to all Docutils developers
|
|
|
|
|
|
:Contact: docutils-develop@lists.sourceforge.net
|
|
|
|
|
|
:Date: $Date: 2015-05-06 18:36:40 +0200 (Mi, 06 Mai 2015) $
|
|
|
|
|
|
:Revision: $Revision: 7887 $
|
|
|
|
|
|
:Copyright: This document has been placed in the public domain.
|
|
|
|
|
|
|
|
|
|
|
|
.. _Docutils: http://docutils.sourceforge.net/
|
|
|
|
|
|
|
|
|
|
|
|
.. contents::
|
|
|
|
|
|
|
|
|
|
|
|
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
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
.. warning:: Docutils is not fit for Universal Wheels. It supports both
|
|
|
|
|
|
Python 2 and 3, but with different code (we use “2to3”). This makes it
|
|
|
|
|
|
a candidate for `Pure Python wheels`_.
|
|
|
|
|
|
|
|
|
|
|
|
As "universal" is false by default, no change to setup.cfg is required.
|
|
|
|
|
|
The wheel builder detects that the package is pure Python and generates
|
|
|
|
|
|
wheels for Py2 and Py3 depending under which python version it runs.
|
|
|
|
|
|
|
|
|
|
|
|
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. [#]_
|
|
|
|
|
|
|
|
|
|
|
|
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".
|
|
|
|
|
|
|
|
|
|
|
|
.. [#] Docutils uses the batteries included with Python and avoids external
|
|
|
|
|
|
dependencies.
|
|
|
|
|
|
|
|
|
|
|
|
.. _bugs275: https://sourceforge.net/p/docutils/bugs/275/
|
|
|
|
|
|
.. _pure python wheels:
|
|
|
|
|
|
https://packaging.python.org/en/latest/distributing.html#pure-python-wheels
|
|
|
|
|
|
.. _feature request 43: https://sourceforge.net/p/docutils/feature-requests/43/
|
|
|
|
|
|
.. _gitpull/setuptools: https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/sandbox/gitpull/setuptools/
|
|
|
|
|
|
.. _setuptools: https://pythonhosted.org/setuptools/
|
|
|
|
|
|
.. _pip: http://pip.readthedocs.org/en/latest/
|
