Merge remote-tracking branch 'origin/master'

Author: Kenneth Reitz

Makefile

@@ -1,2 +1,7 @@
-build:
-	cd docs && make html
+.PHONY: build
+build: html
+
+# this pattern rule lets you run "make build" (or any other target
+# in docs/Makefile) in this directory as though you were in docs/
+%:
+	cd docs && make $@

docs/scenarios/imaging.rst

@@ -35,8 +35,22 @@ Ubuntu 11.04
 Installing on Mac OS X
 ~~~~~~~~~~~~~~~~~~~~~~
 
-.. todo::
-    Notes on installing on Mac OS X
+PIP doesn't know about the Mac OS X Freetype paths. To rectify that:
+
+.. code-block:: bash
+
+    $ ln -s /usr/X11/include/freetype2 /usr/local/include/
+    $ ln -s /usr/X11/include/ft2build.h /usr/local/include/
+    $ ln -s /usr/X11/lib/libfreetype.6.dylib /usr/local/lib/
+    $ ln -s /usr/X11/lib/libfreetype.6.dylib /usr/local/lib/libfreetype.dylib
+
+then:
+
+.. code-block:: bash
+
+    $ brew install libjpeg
+    $ pip install PIL
+
 
 Installing on Windows
 ~~~~~~~~~~~~~~~~~~~~~

docs/shipping/freezing.rst

@@ -8,42 +8,100 @@ Many applications you use every day do this:
 
 - Dropbox
 - BitTorrent
--
-
+- ...
 
 .. todo:: Fill in "Freezing Your Code" stub
 
+
+
+Comparison
+----------
+
+Solutions and platforms/features supported:
+
+=========== ======= ===== ==== ======== ======= ============= ============== ==== =====================
+Solution    Windows Linux OS X Python 3 Licence One-file mode Zipfile import Eggs pkg_resources support
+=========== ======= ===== ==== ======== ======= ============= ============== ==== =====================
+bbFreeze    yes     yes   yes  no       MIT     no            yes            yes  yes                  
+py2exe      yes     no    no   no       MIT     yes           yes            no   no                   
+pyInstaller yes     yes   yes  no       GPL     yes           no             yes  no                   
+cx_Freeze   yes     yes   yes  yes      PSF     no            yes            yes  no                   
+=========== ======= ===== ==== ======== ======= ============= ============== ==== =====================
+
+.. todo:: Add other solutions: py2app
+
+.. note::
+    Freezing Python code on Linux into a Windows executable was only once
+    supported in PyInstaller, `but later dropped
+    <http://stackoverflow.com/questions/2950971/cross-compiling-a-python-script-on-linux-into-a-windows-executable#comment11890276_2951046>`_.
+
+.. note::
+    All solutions need MS Visual C++ dll to be installed on target machine.
+    Only Pyinstaller makes self-executable exe that bundles the dll when
+    passing ``--onefile`` to `Configure.py`.
+
 Windows
-:::::::
+-------
+
+bbFreeze
+~~~~~~~~
+
+Prerequisite is to install :ref:`Python, Distribute and pywin32 dependency on Windows <install-windows>`.
 
+.. todo:: Write steps for most basic .exe
 
 py2exe
-------
+~~~~~~
 
+Prerequisite is to install :ref:`Python on Windows <install-windows>`.
 
+1. Download and install http://sourceforge.net/projects/py2exe/files/py2exe/
 
-OSX
-:::
+2. Write setup.py (`List of configuration options <http://www.py2exe.org/index.cgi/ListOfOptions>`_)::
 
+    from distutils.core import setup
+    import py2exe
 
-py2app
-------
+    setup(
+        windows=[{'script': 'foobar.py'}],
+    )
+
+3. (Optionally) `include icon <http://www.py2exe.org/index.cgi/CustomIcons>`_
 
+4. (Optionally) `one-file mode <http://stackoverflow.com/questions/112698/py2exe-generate-single-executable-file#113014>`_
 
+5. Generate `.exe` into `dist` directory::
 
+   $ python setup.py py2exe
+
+6. Provide the Microsoft Visual C runtime DLL. Two options: `globally install dll on target machine <https://www.microsoft.com/en-us/download/details.aspx?id=29>`_ or `distribute dll aloneside with .exe <http://www.py2exe.org/index.cgi/Tutorial#Step52>`_.
 
 PyInstaller
------------
+~~~~~~~~~~~
+
+Prerequisite is to have installed :ref:`Python, Distribute and pywin32 dependency on Windows <install-windows>`.
+
+- `Most basic tutorial <http://bojan-komazec.blogspot.com/2011/08/how-to-create-windows-executable-from.html>`_
+- `Manual <http://www.pyinstaller.org/export/d3398dd79b68901ae1edd761f3fe0f4ff19cfb1a/project/doc/Manual.html?format=raw>`_
 
 
+OSX
+---
+
+
+py2app
+~~~~~~
+
+PyInstaller
+~~~~~~~~~~~
 
 
 Linux
-:::::
+-----
 
 
 bbFreeze
---------
+~~~~~~~~
 
 PyInstaller
------------
+~~~~~~~~~~~

docs/writing/style.rst

@@ -9,7 +9,7 @@ recognised fact that code is read much more often than it is written.
 One reason for Python code to be easily read and understood is its relatively
 complete set of Code Style guidelines and "Pythonic" idioms.
 
-Moreover, when a veteran Python developer (a Pythonistas) point to some
+Moreover, when a veteran Python developer (a Pythonista) point to some
 parts of a code and say it is not "Pythonic", it usually means that these lines
 of code do not follow the common guidelines and fail to express the intent in
 what is considered the best (hear: most readable) way.
@@ -128,7 +128,7 @@ called with each recipient as an argument: ``send('Hello', 'God', 'Mom',
 'Cthulhu')``, and in the function body ``args`` will be equal to ``('God',
 'Mom', 'Cthulhu')``.
 
-However, this construct has some drawback and should be used with caution. If a
+However, this construct has some drawbacks and should be used with caution. If a
 function receives a list of arguments of the same nature, it is often more
 clear to define it as a function of one argument, that argument being a list or
 any sequence. Here, if ``send`` has multiple recipients, it is better to define
@@ -156,7 +156,7 @@ Python functions that are:
 
 * easy to read (the name and arguments need no explanations)
 
-* easy to change (adding a new keyword argument do not break other parts of the
+* easy to change (adding a new keyword argument does not break other parts of the
   code)
 
 Avoid the magical wand
@@ -178,8 +178,8 @@ possibilities, because it grows the confidence that no hard-wall will be on the
 way.  However, knowing how to use them and particularly when **not** to use
 them is the most important.
 
-Like a Kungfu master, a pythonistas knows how to kill with a single finger, and
-never do it.
+Like a Kungfu master, a Pythonista knows how to kill with a single finger, and
+never to do it.
 
 We are all consenting adults
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~