docs/dev/wheeling.txt

   1 ===========================
   2  Docutils_ Building Wheels
   3 ===========================
   4
   5 :Authors: engelbert gruber; open to all Docutils developers
   6 :Contact: docutils-develop@lists.sourceforge.net
   7 :Date: $Date$
   8 :Revision: $Revision$
   9 :Copyright: This document has been placed in the public domain.
  10
  11 .. _Docutils: http://docutils.sourceforge.net/
  12
  13 .. contents::
  14
  15 Abstract
  16 --------
  17
  18 This document documents trials to build python wheels from Docutils. Once it
  19 is finished it might be driven into distribution or release documentation.
  20
  21 Requests
  22 --------
  23
  24 There is `feature request 43`_ :  Make setup.py build wheels.
  25
  26   Just add this to setup.cfg:
  27
  28   [bdist_wheel]
  29   universal = 1
  30
  31
  32   .. warning:: Docutils is not fit for Universal Wheels. It supports both
  33      Python 2 and 3, but with different code (we use “2to3”). This makes it
  34      a candidate for `Pure Python wheels`_.
  35
  36      As "universal" is false by default, no change to setup.cfg is required.
  37      The wheel builder detects that the package is pure Python and generates
  38      wheels for Py2 and Py3 depending under which python version it runs.
  39
  40 and bugs275_ : Upload wheels to pypi
  41
  42   Currently docutils does not publish any wheels on pypi. Wheels make docutils
  43   faster to install (no need to run setup.py, which for a large number of
  44   packages can take some time), and is no more difficult than uploading an
  45   sdist (see https://packaging.python.org/en/latest/distributing.html#wheels
  46   for instructions).
  47
  48 Logbook
  49 -------
  50
  51 1. Add ``[bdist_wheel] universal = 0`` to setup.cfg.
  52 2. Run ``python setup.py bdist_wheel``::
  53
  54      error: invalid command 'bdist_wheel'
  55
  56 3. setuptools is too old. Install the new one by wheel or source or pip or
  57    easy...
  58
  59 4. try wheel ... first get wheel tar.gz and unpack.
  60
  61 5. try ::
  62
  63      python2.7 wheel-0.24.0/wheel install setuptools-15.0-py2.py3-none-any.whl
  64
  65    no error. But still ``error: invalid command 'bdist_wheel'``::
  66
  67      $ python2.7 setup.py --version
  68      0.12
  69
  70    Did wheel install ? If no, why no error, if yes in which place ?
  71
  72
  73 Logbook: with setuptools branch
  74 -------------------------------
  75
  76 `gitpull/setuptools`_ sandbox branch introduces `setuptools`_ in ``setup.py``.
  77
  78 As of 2015-04-16: **Not working yet**, ``import docutils`` will raise an
  79 ``ImportError``. Need to get packages detected correctly.
  80
  81 Install::
  82
  83     $ svn checkout svn://svn.code.sf.net/p/docutils/code/trunk/sandbox/gitpull/setuptools docutils-setuptools
  84     $ cd setuptools
  85     # create a virtualenv (however you like)
  86     $ pip install -e .
  87
  88 This includes support for generate ``python setup.py bdist_wheel``::
  89
  90     $ python setup.py bdist_wheel
  91     running bdist_wheel
  92     running build
  93     running build_scripts
  94     installing to build/bdist.linux-x86_64/wheel
  95     running install
  96     running install_egg_info
  97     running egg_info
  98     writing docutils.egg-info/PKG-INFO
  99     writing top-level names to docutils.egg-info/top_level.txt
 100     writing dependency_links to docutils.egg-info/dependency_links.txt
 101     reading manifest file 'docutils.egg-info/SOURCES.txt'
 102     reading manifest template 'MANIFEST.in'
 103     warning: no files found matching 'MANIFEST'
 104     warning: no files found matching '*' under directory 'extras'
 105     warning: no previously-included files matching '.cvsignore' found under directory '*'
 106     warning: no previously-included files matching '*~' found under directory '*'
 107     warning: no previously-included files matching '.DS_Store' found under directory '*'
 108     writing manifest file 'docutils.egg-info/SOURCES.txt'
 109     Copying docutils.egg-info to build/bdist.linux-x86_64/wheel/docutils-0.13.data/purelib/docutils-0.13-py2.7.egg-info
 110     running install_scripts
 111     creating build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts
 112     copying build/scripts-2.7/rst2pseudoxml.py -> build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts
 113     copying build/scripts-2.7/rst2man.py -> build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts
 114     copying build/scripts-2.7/rst2odt.py -> build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts
 115     copying build/scripts-2.7/rst2latex.py -> build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts
 116     copying build/scripts-2.7/rstpep2html.py -> build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts
 117     copying build/scripts-2.7/rst2s5.py -> build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts
 118     copying build/scripts-2.7/rst2odt_prepstyles.py -> build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts
 119     copying build/scripts-2.7/rst2html.py -> build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts
 120     copying build/scripts-2.7/rst2html5.py -> build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts
 121     copying build/scripts-2.7/rst2xml.py -> build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts
 122     copying build/scripts-2.7/rst2xetex.py -> build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts
 123     changing mode of build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts/rst2pseudoxml.py to 755
 124     changing mode of build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts/rst2man.py to 755
 125     changing mode of build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts/rst2odt.py to 755
 126     changing mode of build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts/rst2latex.py to 755
 127     changing mode of build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts/rstpep2html.py to 755
 128     changing mode of build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts/rst2s5.py to 755
 129     changing mode of build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts/rst2odt_prepstyles.py to 755
 130     changing mode of build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts/rst2html.py to 755
 131     changing mode of build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts/rst2html5.py to 755
 132     changing mode of build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts/rst2xml.py to 755
 133     changing mode of build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts/rst2xetex.py to 755
 134     creating build/bdist.linux-x86_64/wheel/docutils-0.13.dist-info/WHEEL
 135
 136 Installation::
 137
 138     # create a fresh virtualenv
 139     $ pip install -U dist/docutils-0.13-cp27-none-linux_x86_64.whl
 140     Processing ./dist/docutils-0.13-cp27-none-linux_x86_64.whl
 141     Installing collected packages: docutils
 142     Found existing installation: docutils 0.13
 143     Uninstalling docutils-0.13:
 144     Successfully uninstalled docutils-0.13
 145     Successfully installed docutils-0.13
 146
 147
 148 Logbook with "pip"
 149 ------------------
 150
 151 Docutils' "setup.py" imports from the stdlib's "distutils" module
 152 instead of the 3rd party "setuptools". "distutils" cannot build wheels. [#]_
 153
 154 OTOH, pip_ internally uses "setuptools" instead of "distutils". This way, it
 155 can generate wheels without changes to "setup.py".
 156
 157 1. Install "pip" and "wheels"
 158
 159    Under Debian Gnu/Linux: ``aptitude install python-pip python3-pip``
 160
 161 2. In the repository root directory, run ::
 162
 163       #> pip wheel ./docutils/
 164       Unpacking ./docutils
 165         Running setup.py (path:/tmp/pip-Ym9hKL-build/setup.py) egg_info for package from file:///[...]docutils-svn/docutils
 166
 167           warning: no previously-included files matching '.DS_Store' found under directory '*'
 168       Building wheels for collected packages: docutils
 169         Running setup.py bdist_wheel for docutils
 170         Destination directory: /home/milde/Code/Python/docutils-svn/wheelhouse
 171       Successfully built docutils
 172       Cleaning up...
 173
 174 3. There is a "pure Python" wheel under
 175    ``wheelhouse/docutils-0.13-py2-none-any.whl``
 176
 177 4. Repeat with::
 178
 179      #> pip3 wheel ./docutils/
 180
 181    to get ``wheelhouse/docutils-0.13-py3-none-any.whl``
 182
 183 You can also generate wheels for Docutils 0.12 with ``pip wheel docutils``
 184 and ``pip3 wheel docutils``. The 0.12 archive is downloaded from PIP and
 185 re-packed as wheel. With "pip3" this includes the 2to3 conversion.
 186
 187 Summary:
 188   With the "pip" utility, it is possible to generate wheels for Python 2
 189   and 3 for both, the released and the repository version of Docutils
 190   without changes to the code base.
 191
 192 TODO:
 193   Test-install the wheels.
 194
 195 .. [#] Docutils uses the batteries included with Python and avoids external
 196    dependencies.
 197
 198 .. _bugs275: https://sourceforge.net/p/docutils/bugs/275/
 199 .. _pure python wheels:
 200     https://packaging.python.org/en/latest/distributing.html#pure-python-wheels
 201 .. _feature request 43: https://sourceforge.net/p/docutils/feature-requests/43/
 202 .. _gitpull/setuptools: https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/sandbox/gitpull/setuptools/
 203 .. _setuptools: https://pythonhosted.org/setuptools/
 204 .. _pip: http://pip.readthedocs.org/en/latest/