Merge remote-tracking branch 'origin/master'

Kenneth Reitz · Kenneth Reitz · commit f8b5e7024beb · 2012-01-18T11:13:33.000-05:00
diff --git a/docs/contents.rst.inc b/docs/contents.rst.inc
@@ -24,7 +24,6 @@ This part of the guide focuses on setting up your Python environment.
 
    starting/which-python
    starting/installation
-   starting/next
 
 
 Development Environment
@@ -80,6 +79,7 @@ different scenarios.
    scenarios/admin
    scenarios/ci
    scenarios/speed
+   scenarios/scientific
 
 
 Additional Notes
@@ -92,3 +92,4 @@ Contibution notes and legal information are here (for those interested).
 
    notes/contribute
    notes/license
+   notes/styleguide
diff --git a/docs/dev/env.rst b/docs/dev/env.rst
@@ -223,6 +223,17 @@ IPython
 BPython
 -------
 
+`bpython <http://bpython-interpreter.org/>`_ is an alternative interface to the Python interpreter for Unix-like operating systems. It has the following features:
+
+* In-line syntax highlighting.
+* Readline-like autocomplete with suggestions displayed as you type.
+* Expected parameter list for any Python function.
+* "Rewind" function to pop the last line of code from memory and re-evaluate.
+* Send entered code off to a pastebin.
+* Save entered code to a file.
+* Auto-indentation.
+* Python 3 support.
+
 ::
 
     $ pip install bpython
diff --git a/docs/dev/virtualenvs.rst b/docs/dev/virtualenvs.rst
@@ -1,15 +1,128 @@
 Virtual Environments
 ====================
 
-.. todo:: Explain "Virtual Environments"
+A Virtual Environment, put simply, is an isolated working copy of Python which 
+allows you to work on a specific project without worry of affecting other 
+projects.
+
+For example, you can work on a project which requires Django 1.3 while also 
+maintaining a project which requires Django 1.0.
 
 virtualenv
 ----------
 
-.. todo:: Write about virtualenv
+`virtualenv <http://pypi.python.org/pypi/virtualenv>`_ is a tool to create 
+isolated Python environments.
+
+Install it via pip:
+
+.. code-block:: console
+
+  $ pip install virtualenv
+
+Basic Usage
+~~~~~~~~~~~
+
+1. Create a virtual environment:
+
+.. code-block:: console
+
+   $ virtualenv venv
+
+This creates a copy of Python in whichever directory you ran the command in, 
+placing it in a folder named ``venv``.
+
+2. To begin using the virtual environment, it needs to be activated:
+
+.. code-block:: console
+
+   $ source venv/bin/activate
+
+You can then begin installing any new modules without affecting the system 
+default Python or other virtual environments.
+
+3. If you are done working in the virtual environment for the moment, you can 
+   deactivate it:
+
+.. code-block:: console
+
+   $ deactivate
+
+This puts you back to the system's default Python interpreter with all its 
+installed libraries.
+
+To delete a virtual environment, just delete its folder.
+
+After a while, though, you might end up with a lot of virtual environments 
+littered across your system, and its possible you'll forget their names or 
+where they were placed. 
 
 virtualenvwrapper
 -----------------
 
-.. todo:: Write about virtualenvwrapper
+`virtualenvwrapper <http://www.doughellmann.com/projects/virtualenvwrapper/>`_ 
+provides a set of commands which makes working with virtual environments much 
+more pleasant. It also places all your virtual environments in one place.
+
+To install (make sure **virtualenv** is already installed):
+
+.. code-block:: console
+
+  $ pip install virtualenvwrapper
+  $ export WORKON_HOME=~/Envs
+  $ source /usr/local/bin/virtualenvwrapper.sh
+
+(`Full virtualenvwrapper install instructions <http://www.doughellmann.com/docs/virtualenvwrapper/#introduction>`_.)
+
+Basic Usage
+~~~~~~~~~~~
+
+1. Create a virtual environment:
+
+.. code-block:: console
+
+   $ mkvirtualenv venv
+
+This creates the ``venv`` folder inside ``~/Envs``. 
+
+2. Work on a virtual environment:
+
+.. code-block:: console
+
+   $ workon venv
+
+**virtualenvwrapper** provides tab-completion on environment names. It really 
+helps when you have a lot of environments and have trouble remembering their 
+names. 
+``workon`` also deactivates whatever environment you are currently in, so you 
+can quickly switch between environments.
+
+3. Deactivating is still the same:
+
+.. code-block:: console
+
+   $ deactivate
+
+4. To delete:
+
+.. code-block:: console
+
+   $ rmvirtualenv venv
+
+Other useful commands
+~~~~~~~~~~~~~~~~~~~~~
+
+``lsvirtualenv``
+  List all of the environments.
+
+``cdvirtualenv``
+  Navigate into the directory of the currently activated virtual environment, 
+  so you can browse its ``site-packages``, for example. 
+
+``cdsitepackages``
+  Like the above, but directly into ``site-packages`` directory.
+
+``lssitepackages``
+  Shows contents of ``site-packages`` directory.
 
+`Full list of virtualenvwrapper commands <http://www.doughellmann.com/docs/virtualenvwrapper/command_ref.html#managing-environments>`_.
diff --git a/docs/intro/community.rst b/docs/intro/community.rst
@@ -19,7 +19,7 @@ The mission of the Python Software Foundation is to promote, protect, and advanc
 PEPs
 ----
 
-PEPs are *Python Enhancement Proposals*. They are define change to Python itself, or the standards around it.
+PEPs are *Python Enhancement Proposals*. They describe changes to Python itself, or the standards around it.
 
 There are three different types of PEPs (as defined by `PEP1 <http://www.python.org/dev/peps/pep-0001/>`_):
 
@@ -70,4 +70,4 @@ A comprehensive list of conferences is maintained `at pycon.org <http://www.pyco
 Python User Groups
 --------------------------
 
-User Groups are where a bunch of Python developers meet to present or talk about Python topics of interest. A list of local user groups is maintained at the `Python Software Foundation Wiki <http://wiki.python.org/moin/LocalUserGroups>`_.
+User Groups are where a bunch of Python developers meet to present or talk about Python topics of interest. A list of local user groups is maintained at the `Python Software Foundation Wiki <http://wiki.python.org/moin/LocalUserGroups>`_.
diff --git a/docs/intro/learning.rst b/docs/intro/learning.rst
@@ -47,7 +47,7 @@ While exploring the various features available in the python language the author
 patterns and best practices. 
 
 The book also includes several case studies which have the reader explore the topics discussed in the book 
-in greater detail by applying those topics to real-world examples. Case studies include assingments in GUI
+in greater detail by applying those topics to real-world examples. Case studies include assignments in GUI
 and Markov Analysis.
 
     `Think Python <http://greenteapress.com/thinkpython/html/index.html>`_
diff --git a/docs/intro/news.rst b/docs/intro/news.rst
@@ -19,7 +19,7 @@ Python-related news.
 Python Weekly
 ~~~~~~~~~~~~~
 
-Python Weekly is a free weekly newsletter featureing curated news, articles,
-new releases, jobs etc related to Python.
+Python Weekly is a free weekly newsletter featuring curated news, articles,
+new releases, jobs, etc. related to Python.
 
     `Python Weekly <http://www.pythonweekly.com/>`_
diff --git a/docs/notes/contribute.rst b/docs/notes/contribute.rst
@@ -25,5 +25,3 @@ If you'd like to contribute, there's plenty to do. Here's a short todo_ list.
 
 .. _GitHub: http://github.com/kennethreitz/python-guide/
 .. _todo: https://github.com/kennethreitz/python-guide/blob/master/TODO.rst
-
-.. include:: ../../AUTHORS.rst
diff --git a/docs/scenarios/ci.rst b/docs/scenarios/ci.rst
@@ -7,7 +7,7 @@ Why?
 
 Martin Fowler, who first wrote about `Continuous Integration <http://martinfowler.com/articles/continuousIntegration.html>`_ (short: CI) together with Kent Beck, describes the CI as follows:
 
-    Continuous Integration is a software development practice where members of a team integrate their work frequently, usually each person integrates at least daily - leading to multiple integrations per day. Each integration is verified by an automated build (including test) to detect integration errors as quickly as possible. Many teams find that this approach leads to significantly reduced integration problems and allows a team to develop cohesive software more rapidly. This article is a quick overview of Continuous Integration summarizing the technique and its current usage.
+    Continuous Integration is a software development practice where members of a team integrate their work frequently, usually each person integrates at least daily - leading to multiple integrations per day. Each integration is verified by an automated build (including test) to detect integration errors as quickly as possible. Many teams find that this approach leads to significantly reduced integration problems and allows a team to develop cohesive software more rapidly.
 
 Jenkins
 -------
@@ -29,4 +29,9 @@ Mule?
 Tox
 ---
 
-.. todo:: Write about `Tox <http://codespeak.net/~hpk/tox/>`_
+`tox <https://bitbucket.org/hpk42/tox>`_ is an automation tool providing packaging, testing and deployment of Python software right from the console or CI server.
+It is a generic virtualenv management and test command line tool which provides the following features:
+
+* Checking that packages install correctly with different Python versions and interpreters
+* Running tests in each of the environments, configuring your test tool of choice
+* Acting as a frontend to Continuous Integration servers, reducing boilerplate and merging CI and shell-based testing.
diff --git a/docs/scenarios/gui.rst b/docs/scenarios/gui.rst
@@ -26,12 +26,30 @@ PyObjC
 
 WXPython
 ::::::::
+
+
 Install (Stable)
-----
+----------------
 *Go to http://www.wxpython.org/download.php#stable and download the appropriate package for your OS.*
 
 Gtk
 :::
+PyGTK provides Python bindings for the GTK+ toolkit. Like the GTK+ library
+itself, it is currently licensed under the GNU LGPL. It is worth noting that
+PyGTK only currenty supports the Gtk-2.X API (NOT Gtk-3.0). It is currently
+recommended that PyGTK is not used for new projects and existing applications be
+ported from PyGTK to PyGObject.
+
+Tk
+::
+Tkinter is a thin object-oriented layer on top of Tcl/Tk. It has the advantage
+of being included with the Python standard library, making it the most
+convenient and compatible toolkit to program with.
+
+Both Tk and Tkinter are available on most Unix platforms, as well as on Windows
+and Macintosh systems. Starting with the 8.0 release, Tk offers native look and
+feel on all platforms.
 
-tk
-::
+There's a good multi-language Tk tutorial with Python examples at
+`TkDocs <http://www.tkdocs.com/tutorial/index.html>`_. There's more information
+available on the `Python Wiki <http://wiki.python.org/moin/TkInter>`_.
diff --git a/docs/scenarios/speed.rst b/docs/scenarios/speed.rst
@@ -3,7 +3,32 @@ Speed
 
 CPython, the most commonly used implementation of Python, is slow for CPU bound tasks. `PyPy`_ is fast.
 
-.. todo:: Fill in stub for Speed comparisons
+Using a slightly modified version of `David Beazleys`_ CPU bound test code(added loop for multiple tests), you can see the difference between CPython and PyPy's processing.
+
+::
+
+   PyPy 
+   $ ./pypy -V
+   Python 2.7.1 (7773f8fc4223, Nov 18 2011, 18:47:10)
+   [PyPy 1.7.0 with GCC 4.4.3]
+   $ ./pypy measure2.py
+   0.0683999061584
+   0.0483210086823
+   0.0388588905334
+   0.0440690517426
+   0.0695300102234
+
+::
+
+   CPython
+   $ ./python -V
+   Python 2.7.1
+   $ ./python measure2.py 
+   1.06774401665
+   1.45412397385
+   1.51485204697
+   1.54693889618
+   1.60109114647
 
 Context
 :::::::
@@ -12,7 +37,13 @@ Context
 The GIL
 -------
 
+`The GIL`_ (Global Interpreter Lock) is how Python allows multiple threads to operate at the same time. Python's
+memory management isn't entirely thread-safe, so the GIL is requried to prevents multiple threads from running
+the same Python code at once.
 
+David Beazley has a great `guide`_ on how the GIL operates. He also covers the `new GIL`_ in Python 3.2. His
+results show that maximizing performance in a Python application requires a strong understanding of the GIL,
+how it affects your specific application, how many cores you have, and where your application bottlenecks are.
 
 C Extentions
 ------------
@@ -21,8 +52,8 @@ C Extentions
 The GIL
 -------
 
-
-
+`Special care`_ must be taken when writing C extensions to make sure you register your threads
+with the interpreter.
 
 C Extentions
 ::::::::::::
@@ -57,4 +88,9 @@ Multiprocessing
 ---------------
 
 
-.. _`PyPy`: http://pypy.org
+.. _`PyPy`: http://pypy.org
+.. _`The GIL`: http://wiki.python.org/moin/GlobalInterpreterLock
+.. _`guide`: http://www.dabeaz.com/python/UnderstandingGIL.pdf
+.. _`New GIL`: http://www.dabeaz.com/python/NewGIL.pdf
+.. _`Special care`: http://docs.python.org/c-api/init.html#threads
+.. _`David Beazleys`: http://www.dabeaz.com/GIL/gilvis/measure2.py
diff --git a/docs/scenarios/web.rst b/docs/scenarios/web.rst
diff --git a/docs/starting/installation.rst b/docs/starting/installation.rst
diff --git a/docs/starting/next.rst b/docs/starting/next.rst
diff --git a/docs/writing/documentation.rst b/docs/writing/documentation.rst
