===========================
 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/