realpython · kennethreitz · Jul 15, 2013 · Jun 13, 2013 · Jun 13, 2013 · Jun 13, 2013
diff --git a/docs/dev/env.rst b/docs/dev/env.rst
@@ -14,7 +14,7 @@ VIM
 
 Vim is a text editor which uses keyboard shortcuts for editing instead of menus
 or icons. There exist a couple of plugins and settings for the VIM editor to
-aid python development. If you only develop in Python, a good start is to set
+aid Python development. If you only develop in Python, a good start is to set
 the default settings for indentation and line-wrapping to values compliant with
 `PEP 8 <http://www.python.org/dev/peps/pep-0008/>`_. In your home directory,
 open a file called `.vimrc` and add the following lines:::
@@ -29,7 +29,7 @@ open a file called `.vimrc` and add the following lines:::
 
 With these settings, newlines are inserted after 79 characters and indentation
 is set to 4 spaces per tab. If you also use VIM for other languages, there is a
-handy plugin at indent_, which handles indentation settings for python source
+handy plugin at indent_, which handles indentation settings for Python source
 files.
 
 There is also a handy syntax plugin at syntax_ featuring some improvements over
@@ -67,12 +67,12 @@ Python-mode
 Python-mode_ is a complex solution in VIM for working with python code.
 It has:
 
-- Async python code checking (pylint, pyflakes, pep8, mccabe) in any combination
+- Asynchronous Python code checking (pylint, pyflakes, pep8, mccabe) in any combination
 - Code refactoring and autocompletion with Rope
-- Fast python folding
+- Fast Python folding
 - Virtualenv support
-- Search by python documentation and run python code
-- Auto pep8 error fixes
+- Search by Python documentation and run Python code
+- Auto PEP8 error fixes
 
 And more.
 
@@ -148,7 +148,7 @@ Spyder
 ------
 
 `Spyder <http://code.google.com/p/spyderlib/>`_ is an IDE specifically geared
-toward working with scientific python libraries (namely `Scipy <http://www.scipy.org/>`_).
+toward working with scientific Python libraries (namely `Scipy <http://www.scipy.org/>`_).
 It includes integration with pyflakes_, `pylint <http://www.logilab.org/857>`_,
 and `rope <http://rope.sourceforge.net/>`_.
 
@@ -159,7 +159,7 @@ class and function browser, and object inspection.
 WingIDE
 -------
 
-`WingIDE <http://wingware.com/>`_ is a python specific IDE. It runs on Linux,
+`WingIDE <http://wingware.com/>`_ is a Python specific IDE. It runs on Linux,
 Windows, and Mac (as an X11 application, which frustrates some Mac users).
 
 WingIDE offers code completion, syntax highlighting, source browser, graphical

diff --git a/docs/scenarios/admin.rst b/docs/scenarios/admin.rst
@@ -4,13 +4,14 @@ Systems Administration
 Fabric
 ------
 
-`Fabric <http://docs.fabfile.org>`_ is a library for simplifying system administration tasks. While Chef
-and Puppet tend to focus on managing servers and system libraries,
-fabric is more focused on application level tasks such as deployment.
+`Fabric <http://docs.fabfile.org>`_ is a library for simplifying system
+administration tasks. While Chef and Puppet tend to focus on managing servers
+and system libraries, fabric is more focused on application level tasks such
+as deployment.
 
 Install Fabric:
 
-.. code-block:: bash
+.. code-block:: console
 
     $ pip install fabric
 
@@ -40,7 +41,7 @@ server.
 With the previous code saved in a file named fabfile.py, we can check memory
 usage with:
 
-.. code-block:: bash
+.. code-block:: console
 
     $ fab memory_usage
     [my_server1] Executing task 'memory'
@@ -59,7 +60,7 @@ usage with:
 
 and we can deploy with:
 
-.. code-block:: bash
+.. code-block:: console
 
     $ fab deploy
 
@@ -78,7 +79,7 @@ multiple servers using simple template files.
 
 Salt supports python versions 2.6 and 2.7 and can be installed via pip:
 
-.. code-block:: bash
+.. code-block:: console
 
     $ pip install salt
 
@@ -87,7 +88,7 @@ shell commands or use pre-built modules of complex commands on our minions.
 
 The following command lists all available minion hosts, using the ping module.
 
-.. code-block:: bash
+.. code-block:: console
 
     $ salt '*' test.ping
 
@@ -98,7 +99,7 @@ provide a host taxonomy for the salt modules.
 
 The following command lists all available minions running CentOS using the grains system:
 
-.. code-block:: bash
+.. code-block:: console
 
     $ salt -G 'os:CentOS' test.ping
 

diff --git a/docs/scenarios/gui.rst b/docs/scenarios/gui.rst
@@ -29,14 +29,18 @@ PyObjC
 
 wxPython
 --------
-wxPython is a GUI toolkit for the Python programming language. It allows Python programmers to create programs with a robust, highly functional graphical user interface, simply and easily. It is implemented as a Python extension module (native code) that wraps the popular wxWidgets cross platform GUI library, which is written in C++.
+wxPython is a GUI toolkit for the Python programming language. It allows
+Python programmers to create programs with a robust, highly functional
+graphical user interface, simply and easily. It is implemented as a Python
+extension module (native code) that wraps the popular wxWidgets cross platform
+GUI library, which is written in C++.
 
 Install (Stable)
 ~~~~~~~~~~~~~~~~
 *Go to http://www.wxpython.org/download.php#stable and download the appropriate
 package for your OS.*
 
-Gtk
+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
@@ -60,10 +64,15 @@ available on the `Python Wiki <http://wiki.python.org/moin/TkInter>`_.
 
 Kivy
 ----
-`Kivy <http://kivy.org>`_ is a Python library for development of multi-touch enabled media rich applications. The aim is to allow for quick and easy interaction design and rapid prototyping, while making your code reusable and deployable.
+`Kivy <http://kivy.org>`_ is a Python library for development of multi-touch
+enabled media rich applications. The aim is to allow for quick and easy
+interaction design and rapid prototyping, while making your code reusable
+and deployable.
 
-Kivy is written in Python, based on OpenGL and supports different input devices such as: Mouse, Dual Mouse, TUIO, WiiMote, WM_TOUCH, HIDtouch, Apple's products and so on.
+Kivy is written in Python, based on OpenGL and supports different input devices
+such as: Mouse, Dual Mouse, TUIO, WiiMote, WM_TOUCH, HIDtouch, Apple's products and so on.
 
-Kivy is actively being developed by a community and free to use. It operates on all major platforms (Linux, OSX, Windows, Android).
+Kivy is actively being developed by a community and free to use. It operates
+on all major platforms (Linux, OSX, Windows, Android).
 
 The main resource for information is the website: http://kivy.org
diff --git a/docs/scenarios/network.rst b/docs/scenarios/network.rst
@@ -4,10 +4,10 @@ Networking
 Twisted
 -------
 
-`Twisted <http://twistedmatrix.com/trac/>`_ is an event-driven networking engine. It can be
-used to build applications around many different networking protocols, including http servers
-and clients, applications using SMTP, POP3, IMAP or SSH protocols, instant messaging and
-`many more <http://twistedmatrix.com/trac/wiki/Documentation>`_.
+`Twisted <http://twistedmatrix.com/trac/>`_ is an event-driven networking
+engine. It can be used to build applications around many different networking
+protocols, including http servers and clients, applications using SMTP, POP3,
+IMAP or SSH protocols, instant messaging and `much more <http://twistedmatrix.com/trac/wiki/Documentation>`_.
 
 PyZMQ
 -----

diff --git a/docs/starting/install/osx.rst b/docs/starting/install/osx.rst
@@ -26,6 +26,11 @@ by downloading `XCode <http://developer.apple.com/xcode/>`_, the smaller
 Apple account) or the even smaller `OSX-GCC-Installer <https://github.com/kennethreitz/osx-gcc-installer#readme>`_
 package.
 
+.. note::
+    If you already have XCode installed, do not install OSX-GCC-Installer.
+    In combination, the software can cause issues that are difficult to
+    diagnose.
+
 While Lion comes with a large number of UNIX utilities, those familiar with
 Linux systems will notice one key component missing: a decent package manager.
 `Homebrew <http://mxcl.github.com/homebrew/>`_ fills this void.

diff --git a/docs/starting/which-python.rst b/docs/starting/which-python.rst
@@ -52,11 +52,11 @@ level of compatibility with Python packages and C extension modules.
 
 If you are writing open-source Python code and want to reach the widest possible
 audience, targeting CPython is your best bet. If you need to use any packages
-that rely on C extensions for their functionality (eg: numpy) then CPython
+that rely on C extensions for their functionality (e.g. numpy) then CPython
 is your only choice.
 
 Being the reference implementation, all versions of the Python language are
-available as CPython. Python 3 is only available in a CPython implementation.
+available as CPython. Python 3 is only available as a CPython implementation.
 
 PyPy
 ----
@@ -78,14 +78,14 @@ Jython
 ------
 
 `Jython <http://www.jython.org/>`_ is a Python implementation that compiles
-Python code to Java byte code that then executes on a JVM. It has the additional
-advantage of being able to import and use any Java class the same as a Python
+Python code to Java byte code that is then executed in a JVM. It has the additional
+advantage of being able to import and use any Java class like a Python
 module.
 
 If you need to interface with an existing Java codebase or have other reasons to
 need to write Python code for the JVM, Jython is the best choice.
 
-Currently Jython supports up to Python 2.5. [#jython_ver]_
+Jython currently supports up to Python 2.5. [#jython_ver]_
 
 IronPython
 ----------
@@ -95,7 +95,7 @@ framework. It can use both Python and .NET framework libraries, and can also
 expose Python code to other .NET languages.
 
 `Python Tools for Visual Studio <http://ironpython.net/tools/>`_ integrates
-IronPython directly in to the Visual Studio development environment, making it
+IronPython directly into the Visual Studio development environment, making it
 an ideal choice for Windows developers.
 
 IronPython supports Python 2.7. [#iron_ver]_

diff --git a/docs/writing/gotchas.rst b/docs/writing/gotchas.rst
@@ -2,11 +2,11 @@ Common Gotchas
 ==============
 
 For the most part, Python aims to be a clean and consistent language that
-avoids surprises, but there are a few cases where newcomers to the language
-often get tripped up.
+avoids surprises. However, there are a few cases that can be confusing to
+newcomers.
 
-Some of these are intentional but potentially surprising. Some could arguably
-be considered language warts. In general though, what follows is a collection
+Some of these cases are intentional but can be potentially surprising. Some
+could arguably be considered language warts. In general though, what follows is a collection
 of potentially tricky behavior that might seem strange at first glance, but is
 generally sensible once you're aware of the underlying cause for the surprise.
 
@@ -157,7 +157,7 @@ What You Should Do Instead
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The most general solution is arguably a bit of a hack. Due to Python's
-afformentioned behavior concerning evaluating default arguments to functions
+aforementioned behavior concerning evaluating default arguments to functions
 (see :ref:`default_args`), you can create a closure that binds immediately to
 its arguments by using a default arg like so: