realpython · kennethreitz · Jun 23, 2014 · Jun 17, 2014 · Jun 17, 2014 · Jun 17, 2014
diff --git a/docs/dev/env.rst b/docs/dev/env.rst
@@ -5,40 +5,40 @@ Your Development Environment
 Text Editors
 ::::::::::::
 
-Just about anything which can edit plain text will work for writing Python code,
+Just about anything that can edit plain text will work for writing Python code,
 however, using a more powerful editor may make your life a bit easier.
 
 
-VIM
+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
+or icons. There are 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
 the default settings for indentation and line-wrapping to values compliant with
 :pep:`8`. In your home directory, open a file called :file:`.vimrc` and add the
 following lines::
 
     set textwidth=79  " lines longer than 79 columns will be broken
     set shiftwidth=4  " operation >> indents 4 columns; << unindents 4 columns
-    set tabstop=4     " an hard TAB displays as 4 columns
+    set tabstop=4     " a hard TAB displays as 4 columns
     set expandtab     " insert spaces when hitting TABs
     set softtabstop=4 " insert/delete 4 spaces when hitting a TAB/BACKSPACE
     set shiftround    " round indent to multiple of 'shiftwidth'
     set autoindent    " align the new line indent with the previous line
 
 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
+is set to 4 spaces per tab. If you also use Vim for other languages, there is a
+handy plugin called indent_, which handles indentation settings for Python source
 files.
 
-There is also a handy syntax plugin at syntax_ featuring some improvements over
-the syntax file included in VIM 6.1.
+There is also a handy syntax plugin called syntax_ featuring some improvements over
+the syntax file included in Vim 6.1.
 
 These plugins supply you with a basic environment for developing in Python.
 To get the most out of Vim, you should continually check your code for syntax
 errors and PEP8 compliance. Luckily PEP8_ and Pyflakes_ will do this for you.
-If your VIM is compiled with :option:`+python` you can also utilize some very handy
+If your Vim is compiled with :option:`+python` you can also utilize some very handy
 plugins to do these checks from within the editor.
 
 For PEP8 checking, install the vim-pep8_ plugin, and for pyflakes you can
@@ -51,7 +51,7 @@ order to do this, add the following lines to your :file:`.vimrc`::
     autocmd BufWritePost *.py call Pyflakes()
     autocmd BufWritePost *.py call Pep8()
 
-If you are already using syntastic_ you can enable it to run Pyflakes on write
+If you are already using syntastic_, you can set it to run Pyflakes on write
 and show errors and warnings in the quickfix window. An example configuration
 to do that which also shows status and warning messages in the statusbar would be::
 
@@ -61,24 +61,26 @@ to do that which also shows status and warning messages in the statusbar would b
     let g:syntastic_auto_loc_list=1
     let g:syntastic_loc_list_height=5
 
+
 Python-mode
 ^^^^^^^^^^^
 
-Python-mode_ is a complex solution in VIM for working with Python code.
+Python-mode_ is a complex solution for working with Python code in Vim.
 It has:
 
 - Asynchronous Python code checking (``pylint``, ``pyflakes``, ``pep8``, ``mccabe``) in any combination
 - Code refactoring and autocompletion with Rope
 - Fast Python folding
 - Virtualenv support
-- Search by Python documentation and run Python code
+- Search through Python documentation and run Python code
 - Auto PEP8_ error fixes
 
 And more.
 
 SuperTab
 ^^^^^^^^
-SuperTab_ is a small VIM plugin that makes code completion more convenient by
+
+SuperTab_ is a small Vim plugin that makes code completion more convenient by
 using ``<Tab>`` key or any other customized keys.
 
 .. _indent: http://www.vim.org/scripts/script.php?script_id=974
@@ -94,9 +96,9 @@ using ``<Tab>`` key or any other customized keys.
 Emacs
 -----
 
-Emacs is a powerful text editor. It's fully programmable (lisp), but
-it can be some work to wire up correctly. A good start if you're
-already an Emacs user is `Python Programming in Emacs`_ at EmacsWiki.
+Emacs is another powerful text editor. It is fully programmable (lisp), but
+it can be some work to wire up correctly. A good start if you're already an
+Emacs user is `Python Programming in Emacs`_ at EmacsWiki.
 
 1. Emacs itself comes with a Python mode.
 2. Python ships with an alternate version:
@@ -155,18 +157,18 @@ 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/>`_).
-It includes integration with pyflakes_, `pylint <http://www.logilab.org/857>`_,
+It includes integration with pyflakes_, `pylint <http://www.logilab.org/857>`_
 and `rope <http://rope.sourceforge.net/>`_.
 
 Spyder is open-source (free), offers code completion, syntax highlighting,
-class and function browser, and object inspection.
+a class and function browser, and object inspection.
 
 
 WingIDE
 -------
 
 `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).
+Windows and Mac (as an X11 application, which frustrates some Mac users).
 
 WingIDE offers code completion, syntax highlighting, source browser, graphical
 debugger and support for version control systems.
@@ -196,8 +198,9 @@ It solves the "Project X depends on version 1.x but, Project Y needs 4.x"
 dilemma, and keeps your global site-packages directory clean and manageable.
 
 `virtualenv <http://www.virtualenv.org/en/latest/index.html>`_ creates
-a folder which contains all the necessary executables to contain the
-packages that a Python project would need. An example workflow is given.
+a folder which contains all the necessary executables to use the
+packages that a Python project would need. An example workflow is given
+below.
 
 Install virtualenv:
 
@@ -230,7 +233,7 @@ The name of the current virtual environment will now appear on the left
 of the prompt (e.g. ``(venv)Your-Computer:your_project UserName$``) to
 let you know that it's active. From now on, any package that you install
 using ``pip`` will be placed in the ``venv`` folder, isolated from the global
-Python installation. 
+Python installation.
 
 Install packages as usual:
 
@@ -259,9 +262,9 @@ the current state of the environment packages. To do this, run
 
 This will create a :file:`requirements.txt` file, which contains a simple
 list of all the packages in the current environment, and their respective
-versions. Later, when a different developer (or you, if you need to re-
-create the environment) can install the same packages, with the same
-versions by running
+versions. Later it will be easier for a different developer (or you, if you
+need to re-create the environment) to install the same packages using the
+same versions:
 
 .. code-block:: console
 
@@ -291,8 +294,8 @@ Put this into your :file:`~/.bash_profile` (Linux/Mac) file:
     $ export VIRTUALENVWRAPPER_VIRTUALENV_ARGS='--no-site-packages'
 
 This will prevent your virtualenvs from relying on your (global) site packages
-directory, so that they are completely separate..
-[note: This is the default behavior for ``virtualenv`` 1.7 and later]
+directory, so that they are completely separate.
+[Note: This is the default behavior for ``virtualenv`` 1.7 and later]
 
 Other Tools
 :::::::::::

diff --git a/docs/intro/duction.rst b/docs/intro/duction.rst
@@ -11,13 +11,13 @@ include:
 
   Python's philosophy focuses on readability, from code blocks
   delineated with significant whitespace to intuitive keywords in
-  place of inscrutable punctuation
+  place of inscrutable punctuation.
 
 * **extensive standard libraries and third party modules for virtually
   any task**
 
   Python is sometimes described with the words "batteries included"
-  for its extensive
+  because of its extensive
   `standard library <http://docs.python.org/library/>`_, which includes
   modules for regular expressions, file IO, fraction handling,
   object serialization, and much more.
@@ -77,13 +77,11 @@ For the Community
 
 All contributions to the Guide are welcome, from Pythonistas of all levels.
 If you think there's a gap in what the Guide covers, fork the Guide on
-GitHub and submit a pull request. 
+GitHub and submit a pull request.
 
-Contributions are welcome from everyone, whether they're an old hand or a 
-first-time Pythonista, and the authors to the Guide will gladly help if you 
-have any questions about the appropriateness, completeness, or accuracy of 
+Contributions are welcome from everyone, whether they're an old hand or a
+first-time Pythonista, and the authors to the Guide will gladly help if you
+have any questions about the appropriateness, completeness, or accuracy of
 a contribution.
 
 To get started working on The Hitchhiker's Guide, see the :doc:`/notes/contribute` page.
-
-
diff --git a/docs/intro/learning.rst b/docs/intro/learning.rst
@@ -7,8 +7,8 @@ Beginner
 The Python Tutorial
 ~~~~~~~~~~~~~~~~~~~~
 
-This is the official tutorial, it covers all the basics, and offers a tour of the
-language and the standard library, recommended for those who need a quickstart
+This is the official tutorial. It covers all the basics, and offers a tour of the
+language and the standard library. Recommended for those who need a quickstart
 guide to the language.
 
     `The Python Tutorial <http://docs.python.org/tutorial/index.html>`_
@@ -189,6 +189,7 @@ Miscellaneous topics
 
 Problem Solving with Algorithms and Data Structures
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 Problem Solving with Algorithms and Data Structures covers a range of data structures and
 algorithms. All concepts are illustrated with Python code along with interactive samples
 that can be run directly in the browser.
@@ -198,8 +199,9 @@ that can be run directly in the browser.
 
 Programming Collective Intelligence
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 Programming Collective Intelligence introduces a wide array of basic machine learning and
-data mining methods. The exposition is not very mathematically formal, but rather focuses 
+data mining methods. The exposition is not very mathematically formal, but rather focuses
 on explaining the underlying intuition and shows how to implement the algorithms in Python.
 
     `Programming Collective Intelligence <http://shop.oreilly.com/product/9780596529321.do>`_
@@ -223,7 +225,7 @@ This is Python's reference manual, it covers the syntax and the core semantics o
 language.
 
     `The Python Language Reference <http://docs.python.org/reference/index.html>`_
-    
+
 Python Pocket Reference
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -237,13 +239,12 @@ Writing Idiomatic Python
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
 "Writing Idiomatic Python", written by Jeff Knupp, contains the most common and
-important Python idioms in a format that maximizes identification and understanding. 
-Each idiom is presented as a recommendation to write some commonly used piece of code.
-It is followed by an explanation of why the idiom is important. It also contains two 
-code samples: the "Harmful" way to write it and the "Idiomatic" way
+important Python idioms in a format that maximizes identification and understanding.
+Each idiom is presented as a recommendation of a way to write some commonly
+used piece of code, followed by an explanation of why the idiom is important.
+It also contains two code samples for each idiom: the "Harmful" way to write it
+and the "Idiomatic" way.
 
 	`For Python 2.7.3+ <http://www.amazon.com/Writing-Idiomatic-Python-2-7-3-Knupp/dp/1482372177/>`_
 
 	`For Python 3.3+  <http://www.amazon.com/Writing-Idiomatic-Python-Jeff-Knupp-ebook/dp/B00B5VXMRG/>`_
-
-
diff --git a/docs/scenarios/admin.rst b/docs/scenarios/admin.rst
@@ -126,9 +126,12 @@ State files can be written using YAML, the Jinja2 template system or pure Python
 
 Psutil
 ------
-`Psutil <https://code.google.com/p/psutil/>`_ is an interface to different system information (e.g. CPU, memory, disks, network, users and processes).
 
-Here is an example to be aware of some server overload. In case of some failed test (net, CPU) it send an email.
+`Psutil <https://code.google.com/p/psutil/>`_ is an interface to different
+system information (e.g. CPU, memory, disks, network, users and processes).
+
+Here is an example to be aware of some server overload. If any of the
+tests (net, CPU) fail, it will send an email.
 
 .. code-block:: python
 
@@ -162,7 +165,7 @@ Here is an example to be aware of some server overload. In case of some failed t
         if counter > 25:
             attack = 0
             counter = 0
-    # Write a very important email if attack is higher then 4
+    # Write a very important email if attack is higher than 4
     TO = "you@your_email.com"
     FROM = "webmaster@your_domain.com"
     SUBJECT = "Your domain is out of system resources!"
@@ -173,32 +176,38 @@ Here is an example to be aware of some server overload. In case of some failed t
     server.quit()
 
 
-A full terminal application like a widely extended top which is based on psutil and with the ability of a client-server
-monitoring is `glance <https://github.com/nicolargo/glances/>`_.
+A full terminal application like a widely extended top which is based on
+psutil and with the ability of a client-server monitoring is
+`glance <https://github.com/nicolargo/glances/>`_.
 
 Ansible
 -------
-`Ansible <http://ansible.com/>`_  is a open source system automation tool. The biggest advantage over Puppet or Chef is it does not require an agent on the client machine. Playbooks are Ansible’s configuration, deployment, and orchestration language and are written in in yaml with jinja2 for templating.
+
+`Ansible <http://ansible.com/>`_  is an open source system automation tool.
+The biggest advantage over Puppet or Chef is it does not require an agent on
+the client machine. Playbooks are Ansible’s configuration, deployment, and
+orchestration language and are written in in YAML with Jinja2 for templating.
 
 Ansible supports Python versions 2.6 and 2.7 and can be installed via pip:
 
 .. code-block:: console
 
     $ pip install ansible
 
-Ansible requires a inventory file that describes the hosts it has access to. Here is an example of a host and
-playbook that will ping all the hosts in the inventory file:
+Ansible requires an inventory file that describes the hosts to which it has
+access. Below is an example of a host and playbook that will ping all the
+hosts in the inventory file.
 
 Here is an example inventory file:
-hosts.yml
+:file:`hosts.yml`
 
 .. code-block:: yaml
 
     [server_name]
     127.0.0.1
 
 Here is an example playbook:
-ping.yml
+:file:`ping.yml`
 
 .. code-block:: yaml
 
@@ -207,17 +216,17 @@ ping.yml
 
       tasks:
         - name: ping
-          action: ping      
+          action: ping
 
 To run the playbook:
 
 .. code-block:: console
 
     $ ansible-playbook ping.yml -i hosts.yml --ask-pass
 
-That Ansible playbook will ping all of the servers in the hosts.yml file. You can also select groups of servers using Ansible. For more information about Ansible read the docs.
-
-`Ansible Docs <http://docs.ansible.com/>`_ 
+The Ansible playbook will ping all of the servers in the :file:`hosts.yml` file.
+You can also select groups of servers using Ansible. For more information
+about Ansible, read the `Ansible Docs <http://docs.ansible.com/>`_.
 
 
 Chef