More typo, grammar, and style fixes

docs/scenarios/admin.rst

@@ -23,7 +23,7 @@ Install Fabric:
 
 The following code will create two tasks that we can use: ``memory_usage`` and
 ``deploy``. The former will output the memory usage on each machine. The
-latter will ssh into each server, cd to our project directory, activate the
+latter will SSH into each server, cd to our project directory, activate the
 virtual environment, pull the newest codebase, and restart the application
 server.
 
@@ -101,7 +101,7 @@ The following command lists all available minion hosts, using the ping module.
 
     $ salt '*' test.ping
 
-The host filtering is accomplished by matching the minion id,
+The host filtering is accomplished by matching the minion id
 or using the grains system. The
 `grains <http://docs.saltstack.org/en/latest/topics/targeting/grains.html>`_
 system uses static host information like the operating system version or the
@@ -131,7 +131,7 @@ it will install and start the Apache server:
         - require:
           - pkg: apache
 
-State files can be written using YAML, the Jinja2 template system or pure Python.
+State files can be written using YAML, the Jinja2 template system, or pure Python.
 
     `Salt Documentation <http://docs.saltstack.com>`_
 
@@ -141,7 +141,7 @@ Psutil
 ******
 
 `Psutil <https://github.com/giampaolo/psutil/>`_ is an interface to different
-system information (e.g. CPU, memory, disks, network, users and processes).
+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.
@@ -263,9 +263,9 @@ configures itself and this distributed approach makes Chef a scalable automation
 
 Chef works by using custom recipes (configuration elements), implemented in cookbooks. Cookbooks, which are basically
 packages for infrastructure choices, are usually stored in your Chef server.
-Read the `Digital Ocean tutorial series
+Read the `DigitalOcean tutorial series
 <https://www.digitalocean.com/community/tutorials/how-to-install-a-chef-server-workstation-and-client-on-ubuntu-vps-instances>`_
-on chef to learn how to create a simple Chef Server.
+on Chef to learn how to create a simple Chef Server.
 
 To create a simple cookbook the `knife <https://docs.chef.io/knife.html>`_ command is used:
 
@@ -299,8 +299,8 @@ Puppet Agents are installed on nodes whose state needs to be monitored or
 changed.  A designated server known as the Puppet Master is responsible for
 orchestrating the agent nodes.
 
-Agent nodes send basic facts about the system such as to the operating system,
-kernel, architecture, ip address, hostname etc. to the Puppet Master.
+Agent nodes send basic facts about the system such as the operating system,
+kernel, architecture, IP address, hostname, etc. to the Puppet Master.
 The Puppet Master then compiles a catalog with information provided by the
 agents on how each node should be configured and sends it to the agent. The
 agent enforces the change as prescribed in the catalog and sends a report back
@@ -320,7 +320,7 @@ your Puppet modules.
     Ubuntu
 
 Writing Modules in Puppet is pretty straight forward. Puppet Manifests together
-form Puppet Modules. Puppet manifest end with an extension of ``.pp``.
+form Puppet Modules. Puppet manifests end with an extension of ``.pp``.
 Here is an example of 'Hello World' in Puppet.
 
 .. code-block:: puppet
@@ -334,7 +334,7 @@ Here is an example of 'Hello World' in Puppet.
 Here is another example with system based logic. Note how the operating system
 fact is being used as a variable prepended with the ``$`` sign. Similarly, this
 holds true for other facts such as hostname which can be referenced by
-``$hostname``
+``$hostname``.
 
 .. code-block:: puppet
 
@@ -346,10 +346,10 @@ holds true for other facts such as hostname which can be referenced by
     }
 
 There are several resource types for Puppet but the package-file-service
-paradigm is all you need for undertaking majority of the configuration
+paradigm is all you need for undertaking the majority of the configuration
 management. The following Puppet code makes sure that the OpenSSH-Server
 package is installed in a system and the sshd service is notified to restart
-everytime the sshd configuration file is changed.
+every time the sshd configuration file is changed.
 
 .. code-block:: puppet
 
@@ -407,6 +407,6 @@ monitoring framework written in Python. Its main goal is to give users a flexibl
 architecture for their monitoring system that is designed to scale to large
 environments.
 
-Shinken is backwards-compatible with the Nagios configuration standard, and
-plugins.It works on any operating system, and architecture that supports Python
-which includes Windows, GNU/Linux, and FreeBSD.
+Shinken is backwards-compatible with the Nagios configuration standard and
+plugins. It works on any operating system and architecture that supports Python,
+which includes Windows, Linux, and FreeBSD.

docs/scenarios/ci.rst

@@ -14,7 +14,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:
+(short: CI) together with Kent Beck, describes CI as follows:
 
     Continuous Integration is a software development practice where members of
     a team integrate their work frequently, usually each person integrates at
@@ -29,8 +29,7 @@ Martin Fowler, who first wrote about `Continuous Integration <http://martinfowle
 Jenkins
 *******
 
-`Jenkins CI <http://jenkins-ci.org>`_ is an extensible continuous integration
-engine. Use it.
+`Jenkins CI <http://jenkins-ci.org>`_ is an extensible Continuous Integration engine. Use it.
 
 
 ********
@@ -46,7 +45,7 @@ Tox
 ***
 
 `tox <https://tox.readthedocs.io/en/latest/>`_ is an automation tool providing
-packaging, testing and deployment of Python software right from the console or
+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:
 
@@ -55,7 +54,7 @@ which provides the following features:
 * Running tests in each of the environments, configuring your test tool of
   choice
 * Acting as a front-end to Continuous Integration servers, reducing boilerplate
-  and merging CI and shell-based testing.
+  and merging CI and shell-based testing
 
 
 *********
@@ -66,7 +65,7 @@ Travis-CI
 tests for open source projects for free. It provides multiple workers to run
 Python tests on and seamlessly integrates with GitHub. You can even have it
 comment on your Pull Requests whether this particular changeset breaks the
-build or not. So if you are hosting your code on GitHub, travis-ci is a great
+build or not. So if you are hosting your code on GitHub, Travis-CI is a great
 and easy way to get started with Continuous Integration.
 
 In order to get started, add a :file:`.travis.yml` file to your repository with
@@ -86,12 +85,12 @@ this example content::
 
 
 This will get your project tested on all the listed Python versions by
-running the given script, and will only build the master branch. There are a
-lot more options you can enable, like notifications, before and after steps
-and much more. The `travis-ci docs <https://docs.travis-ci.com/user/languages/python/>`_
+running the given script, and will only build the ``master`` branch. There are a
+lot more options you can enable, like notifications, before and after steps,
+and much more. The `Travis-CI docs <https://docs.travis-ci.com/user/languages/python/>`_
 explain all of these options, and are very thorough.
 
-In order to activate testing for your project, go to `the travis-ci site <https://travis-ci.org/>`_
+In order to activate testing for your project, go to `the Travis-CI site <https://travis-ci.org/>`_
 and login with your GitHub account. Then activate your project in your
 profile settings and you're ready to go. From now on, your project's tests
 will be run on every push to GitHub.

docs/scenarios/cli.rst

@@ -15,12 +15,12 @@ switches.
 
 Some popular command-line applications include:
 
-* `Grep <http://en.wikipedia.org/wiki/Grep>`_ - A plain-text data search utility
+* `grep <http://en.wikipedia.org/wiki/grep>`_ - A plain-text data search utility
 * `curl <http://curl.haxx.se/>`_ - A tool for data transfer with URL syntax
-* `httpie <https://github.com/jakubroztocil/httpie>`_ - A command line HTTP
+* `httpie <https://github.com/jakubroztocil/httpie>`_ - A command-line HTTP
   client, a user-friendly cURL replacement
-* `git <http://git-scm.com/>`_ - A distributed version control system
-* `mercurial <https://www.mercurial-scm.org/>`_ - A distributed version control
+* `Git <http://git-scm.com/>`_ - A distributed version control system
+* `Mercurial <https://www.mercurial-scm.org/>`_ - A distributed version control
   system primarily written in Python
 
 
@@ -30,8 +30,8 @@ Clint
 
 `clint <https://pypi.python.org/pypi/clint/>`_ is a Python module which is
 filled with very useful tools for developing command-line applications.
-It supports features such as; CLI colors and indents, simple and powerful
-column printer, iterator based progress bars and implicit argument handling.
+It supports features such as: CLI colors and indents, simple and powerful
+column printer, iterator based progress bars, and implicit argument handling.
 
 
 *****
@@ -40,7 +40,7 @@ Click
 
 `click <http://click.pocoo.org/>`_ is a Python package for creating
 command-line interfaces in a composable way with as little code as
-possible. This “Command-line Interface Creation Kit” is highly
+possible. This “Command-Line Interface Creation Kit” is highly
 configurable but comes with good defaults out of the box.
 
 
@@ -61,8 +61,8 @@ Plac
 over the Python standard library `argparse <http://docs.python.org/2/library/argparse.html>`_,
 which hides most of its complexity by using a declarative interface: the
 argument parser is inferred rather than written down by imperatively. This
-module targets especially unsophisticated users, programmers, sys-admins,
-scientists and in general people writing throw-away scripts for themselves,
+module targets especially unsophisticated users, programmers, sysadmins,
+scientists, and in general people writing throw-away scripts for themselves,
 who choose to create a command-line interface because it is quick and simple.
 
 
@@ -73,7 +73,7 @@ Cliff
 `Cliff <http://docs.openstack.org/developer/cliff/>`_  is a framework for
 building command-line programs. It uses setuptools entry points to provide
 subcommands, output formatters, and other extensions. The framework is meant
-to be used to create multi-level commands such as subversion and git, where
+to be used to create multi-level commands such as ``svn`` and ``git``, where
 the main program handles some basic argument parsing and then invokes a
 sub-command to do the work.
 
@@ -83,11 +83,11 @@ Cement
 ******
 
 `Cement <http://builtoncement.com/>`_ is an advanced CLI Application Framework.
-Its goal is to introduce a standard, and feature-full platform
+Its goal is to introduce a standard and feature-full platform
 for both simple and complex command line applications as well
 as support rapid development needs without sacrificing quality.
-Cement is flexible, and it's use cases span from the simplicity of a micro-framework
-to the complexity of a meg-framework.
+Cement is flexible, and its use cases span from the simplicity of a micro-framework
+to the complexity of a mega-framework.
 
 
 ***********
@@ -95,9 +95,8 @@ Python Fire
 ***********
 
 `Python Fire <https://github.com/google/python-fire/>`_ is a library for
-automatically generating command line interfaces from absolutely any Python
+automatically generating command-line interfaces from absolutely any Python
 object. It can help debug Python code more easily from the command line,
 create CLI interfaces to existing code, allow you to interactively explore
 code in a REPL, and simplify transitioning between Python and Bash (or any
 other shell).
-

docs/scenarios/clibs.rst

@@ -36,11 +36,11 @@ ABI Interaction
 ctypes
 ******
 
-`ctypes <https://docs.python.org/3/library/ctypes.html>`_ is the de facto
+`ctypes <https://docs.python.org/3/library/ctypes.html>`_ is the de facto standard
 library for interfacing with C/C++ from CPython, and it provides not only
 full access to the native C interface of most major operating systems (e.g.,
 kernel32 on Windows, or libc on \*nix), but also provides support for loading
-and interfacing with dynamic libraries, such as DLLs or shared objects at
+and interfacing with dynamic libraries, such as DLLs or shared objects, at
 runtime. It does bring along with it a whole host of types for interacting
 with system APIs, and allows you to rather easily define your own complex
 types, such as structs and unions, and allows you to modify things such as
@@ -82,7 +82,7 @@ large number of scripting languages), is a tool for generating bindings for
 interpreted languages from C/C++ header files. It is extremely simple to use:
 the consumer simply needs to define an interface file (detailed in the
 tutorial and documentations), include the requisite C/C++ headers, and run
-the build tool against them. While it does have some limits, (it currently
+the build tool against them. While it does have some limits (it currently
 seems to have issues with a small subset of newer C++ features, and getting
 template-heavy code to work can be a bit verbose), it provides a great deal
 of power and exposes lots of features to Python with little effort.
@@ -137,5 +137,5 @@ Boost.Python
 `Boost.Python <http://www.boost.org/doc/libs/1_59_0/libs/python/doc/>`_
 requires a bit more manual work to expose C++ object functionality, but
 it is capable of providing all the same features SWIG does and then some,
-to include providing wrappers to access PyObjects in C++, extracting SWIG-
+to include providing wrappers to access PyObjects in C++, extracting SWIG
 wrapper objects, and even embedding bits of Python into your C++ code.

docs/scenarios/crypto.rst

@@ -7,16 +7,16 @@ Cryptography
 
 
 ************
-Cryptography
+cryptography
 ************
 
-`Cryptography <https://cryptography.io/en/latest/>`_ is an actively developed
+`cryptography <https://cryptography.io/en/latest/>`_ is an actively developed
 library that provides cryptographic recipes and primitives. It supports
-Python 2.6-2.7, Python 3.3+ and PyPy.
+Python 2.6-2.7, Python 3.3+, and PyPy.
 
 
-Cryptography is divided into two layers of recipes and hazardous materials
-(hazmat).  The recipes layer provides simple API for proper symmetric
+cryptography is divided into two layers of recipes and hazardous materials
+(hazmat).  The recipes layer provides a simple API for proper symmetric
 encryption and the hazmat layer provides low-level cryptographic primitives.
 
 
@@ -46,9 +46,9 @@ Example code using high level symmetric encryption recipe:
 GPGME bindings
 **************
 
-The `GPGME Python bindings <https://dev.gnupg.org/source/gpgme/browse/master/lang/python/>`_ provide pythonic access to `GPG Made Easy <https://dev.gnupg.org/source/gpgme/browse/master/>`_, a C API for the entire GNU Privacy Guard suite of projects, including GPG, libgcrypt and gpgsm (the S/MIME engine). It supports Python 2.6, 2.7, 3.4 and above. Depends on the SWIG C interface for Python as well as the GnuPG software and libraries.
+The `GPGME Python bindings <https://dev.gnupg.org/source/gpgme/browse/master/lang/python/>`_ provide Pythonic access to `GPG Made Easy <https://dev.gnupg.org/source/gpgme/browse/master/>`_, a C API for the entire GNU Privacy Guard suite of projects, including GPG, libgcrypt, and gpgsm (the S/MIME engine). It supports Python 2.6, 2.7, 3.4, and above. Depends on the SWIG C interface for Python as well as the GnuPG software and libraries.
 
-A more comprehensive `GPGME Python Bindings HOWTO <https://dev.gnupg.org/source/gpgme/browse/master/lang/python/docs/GPGMEpythonHOWTOen.org>`_ is available with the source and a HTML version is available `here <http://files.au.adversary.org/crypto/GPGMEpythonHOWTOen.html>`_.  Python 3 sample scripts from the examples in the HOWTO are also provided with the source and are accessible `here <https://dev.gnupg.org/source/gpgme/browse/master/lang/python/examples/howto/>`_.
+A more comprehensive `GPGME Python Bindings HOWTO <https://dev.gnupg.org/source/gpgme/browse/master/lang/python/docs/GPGMEpythonHOWTOen.org>`_ is available with the source, and an HTML version is available `here <http://files.au.adversary.org/crypto/GPGMEpythonHOWTOen.html>`_.  Python 3 sample scripts from the examples in the HOWTO are also provided with the source and are accessible `here <https://dev.gnupg.org/source/gpgme/browse/master/lang/python/examples/howto/>`_.
 
 Available under the same terms as the rest of the GnuPG Project: GPLv2 and LGPLv2.1, both with the "or any later version" clause.
 

docs/scenarios/db.rst

@@ -12,7 +12,7 @@ DB-API
 
 The Python Database API (DB-API) defines a standard interface for Python
 database access modules. It's documented in :pep:`249`.
-Nearly all Python database modules such as `sqlite3`, `psycopg` and
+Nearly all Python database modules such as `sqlite3`, `psycopg`, and
 `mysql-python` conform to this interface.
 
 Tutorials that explain how to work with modules that conform to this interface can be found
@@ -39,7 +39,7 @@ Records
 
 `Records <https://github.com/kennethreitz/records>`_ is minimalist SQL library,
 designed for sending raw SQL queries to various databases. Data can be used
-programmatically, or exported to a number of useful data formats.
+programmatically or exported to a number of useful data formats.
 
 .. code-block:: console
 
@@ -73,11 +73,11 @@ peewee
 
 `peewee <http://docs.peewee-orm.com/en/latest/>`_ is another ORM with a focus
 on being lightweight with support for Python 2.6+ and 3.2+ which supports
-SQLite, MySQL and Postgres by default. The
+SQLite, MySQL, and PostgreSQL by default. The
 `model layer <https://peewee.readthedocs.io/en/latest/peewee/quickstart.html#model-definition>`_
 is similar to that of the Django ORM and it has
 `SQL-like methods <https://peewee.readthedocs.io/en/latest/peewee/quickstart.html#retrieving-data>`_
-to query data. While SQLite, MySQL and Postgres are supported out-of-the-box,
+to query data. While SQLite, MySQL, and PostgreSQL are supported out-of-the-box,
 there is a `collection of add-ons <https://peewee.readthedocs.io/en/latest/peewee/playhouse.html#playhouse>`_
 available.
 
@@ -88,9 +88,9 @@ PonyORM
 
 `PonyORM <http://ponyorm.com/>`_ is an ORM that takes a different approach to
 querying the database. Instead of writing an SQL-like language or boolean
-expressions, Python's generator syntax is used. There's also an graphical
+expressions, Python's generator syntax is used. There's also a graphical
 schema editor that can generate PonyORM entities for you. It supports Python
-2.6+ and Python 3.3+ and can connect to SQLite, MySQL, Postgres & Oracle
+2.6+ and Python 3.3+ and can connect to SQLite, MySQL, PostgreSQL, and Oracle.
 
 
 *********
@@ -98,8 +98,8 @@ SQLObject
 *********
 
 `SQLObject <http://www.sqlobject.org/>`_ is yet another ORM. It supports a wide
-variety of databases: Common database systems MySQL, Postgres and SQLite and
-more exotic systems like SAP DB, SyBase and MSSQL. It only supports Python 2
+variety of databases: common database systems like MySQL, PostgreSQL, and SQLite and
+more exotic systems like SAP DB, SyBase, and Microsoft SQL Server. It only supports Python 2
 from Python 2.6 upwards.
 
-.. There's no official information on this on their page, this information was gathered by looking at their source code
+.. There's no official information on this on their page; this information was gathered by looking at their source code.

docs/scenarios/gui.rst

@@ -14,12 +14,12 @@ Camelot
 *******
 
 `Camelot <http://www.python-camelot.com>`_ provides components for building
-applications on top of Python, SQLAlchemy and Qt.  It is inspired by
+applications on top of Python, SQLAlchemy, and Qt.  It is inspired by
 the Django admin interface.
 
 The main resource for information is the website:
 http://www.python-camelot.com
-and the mailing list https://groups.google.com/forum/#!forum/project-camelot
+and the mailing list https://groups.google.com/forum/#!forum/project-camelot.
 
 
 *****
@@ -44,7 +44,7 @@ applications be ported from PyGTK to PyGObject.
 PyGObject aka (PyGi)
 ********************
 
-`PyGObject <https://wiki.gnome.org/Projects/PyGObject>`_ provides Python bindings, which gives access to the entire GNOME software platform.
+`PyGObject <https://wiki.gnome.org/Projects/PyGObject>`_ provides Python bindings which gives access to the entire GNOME software platform.
 It is fully compatible with GTK+ 3. Here is a tutorial to get started with `Python GTK+ 3 Tutorial <https://python-gtk-3-tutorial.readthedocs.io/en/latest/>`_.
 
 `API Reference <http://lazka.github.io/pgi-docs/>`_
@@ -59,8 +59,8 @@ 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
+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 is free to use. It operates
@@ -111,7 +111,7 @@ application source code to be executed as a standalone desktop application.
 
 `Python Wiki for PyjamasDesktop <http://wiki.python.org/moin/PyjamasDesktop>`_.
 
-The main website; `pyjs Desktop <http://pyjs.org/>`_.
+The main website: `pyjs Desktop <http://pyjs.org/>`_.
 
 
 **
@@ -127,13 +127,13 @@ non-GUI applications.
 PySimpleGUI
 ***********
 
-`PySimpleGUI <https://pysimplegui.readthedocs.io/>`_ is a  wrapper for Tkinter and Qt (others on the way).  The amount of code required to implement custom GUIs is much shorter using PySimpleGUI than if the same GUI were written directly using tkinter or Qt.  PySimpleGUI code can be "ported" between GUI frameworks by changing import statement.
+`PySimpleGUI <https://pysimplegui.readthedocs.io/>`_ is a  wrapper for Tkinter and Qt (others on the way).  The amount of code required to implement custom GUIs is much shorter using PySimpleGUI than if the same GUI were written directly using Tkinter or Qt.  PySimpleGUI code can be "ported" between GUI frameworks by changing import statements.
 
 .. code-block:: console
 
   $ pip install pysimplegui
 
-PySimpleGUI is contained in a single PySimpleGUI.py file.  Should pip installation be impossible, pasting the PySimpleGUI.py file into a project's folder is all that's required to import and begin using.
+PySimpleGUI is contained in a single PySimpleGUI.py file.  Should pip installation be impossible, copying the PySimpleGUI.py file into a project's folder is all that's required to import and begin using.
 
 
 ****
@@ -145,7 +145,7 @@ native, cross platform GUI toolkit. Toga consists of a library of base
 components with a shared interface to simplify platform-agnostic GUI
 development.
 
-Toga is available on Mac OS, Windows, Linux (GTK), and mobile platforms such
+Toga is available on mOS, Windows, Linux (GTK), and mobile platforms such
 as Android and iOS.
 
 

docs/scenarios/imaging.rst

@@ -6,7 +6,7 @@ Image Manipulation
 .. image:: /_static/photos/34575689432_3de8e9a348_k_d.jpg
 
 Most image processing and manipulation techniques can be carried out
-effectively using two libraries: Python Imaging Library (PIL)  and OpenSource
+effectively using two libraries: Python Imaging Library (PIL) and Open Source
 Computer Vision (OpenCV).
 
 A brief description of both is given below.
@@ -21,8 +21,8 @@ for short, is one of the core libraries for image manipulation in Python. Unfort
 its development has stagnated, with its last release in 2009.
 
 Luckily for you, there's an actively-developed fork of PIL called
-`Pillow <http://python-pillow.github.io/>`_ - it's easier to install, runs on
-all operating systems, and supports Python 3.
+`Pillow <http://python-pillow.github.io/>`_ -- it's easier to install, runs on
+all major operating systems, and supports Python 3.
 
 Installation
 ~~~~~~~~~~~~
@@ -65,11 +65,11 @@ There are more examples of the Pillow library in the
 `Pillow tutorial <https://pillow.readthedocs.io/en/3.0.x/handbook/tutorial.html>`_.
 
 
-**************************
-OpenSource Computer Vision
-**************************
+***************************
+Open Source Computer Vision
+***************************
 
-OpenSource Computer Vision, more commonly known as OpenCV, is a more advanced
+Open Source Computer Vision, more commonly known as OpenCV, is a more advanced
 image manipulation and processing software than PIL. It has been implemented
 in several languages and is widely used.
 

docs/scenarios/json.rst

@@ -52,7 +52,7 @@ You can also convert the following to JSON:
 simplejson
 **********
 
-The JSON library was added to Python in version 2.6.
+The json library was added to Python in version 2.6.
 If you're using an earlier version of Python, the
 `simplejson <https://simplejson.readthedocs.io/en/latest/>`_ library is
 available via PyPI.
@@ -68,5 +68,5 @@ importing simplejson under a different name:
 
     import simplejson as json
 
-After importing simplejson as json, the above examples will all work as if you
+After importing simplejson as `json`, the above examples will all work as if you
 were using the standard json library.

docs/scenarios/ml.rst

@@ -6,16 +6,16 @@ Machine Learning
 
 .. image:: /_static/photos/34018729885_002ced9b54_k_d.jpg
 
-Python has a vast number of libraries for data analysis, statistics and Machine Learning itself, making it a language of choice for many data scientists.
+Python has a vast number of libraries for data analysis, statistics, and Machine Learning itself, making it a language of choice for many data scientists.
 
-Some widely used packages for Machine Learning and other Data Science applications are enlisted below.
+Some widely used packages for Machine Learning and other data science applications are listed below.
 
 
 ***********
-Scipy Stack
+SciPy Stack
 ***********
 
-The Scipy stack consists of a bunch of core helper packages used in data science, for statistical analysis and visualising data. Because of its huge number of functionalities and ease of use, the Stack is considered a must-have for most data science applications.
+The SciPy stack consists of a bunch of core helper packages used in data science for statistical analysis and visualising data. Because of its huge number of functionalities and ease of use, the Stack is considered a must-have for most data science applications.
 
 The Stack consists of the following packages (link to documentation given):
 
@@ -41,9 +41,9 @@ For installing the full stack, or individual packages, you can refer to the inst
 scikit-learn
 ************
 
-Scikit is a free and open-source machine learning library for Python. It offers off-the-shelf functions to implement many algorithms like linear regression, classifiers, SVMs, k-means, Neural Networks etc. It also has a few sample datasets which can be directly used for training and testing.
+Scikit is a free and open-source machine learning library for Python. It offers off-the-shelf functions to implement many algorithms like linear regression, classifiers, SVMs, k-means, Neural Networks, etc. It also has a few sample datasets which can be directly used for training and testing.
 
-Because of its speed, robustness and easiness to use, it's one of the most widely-used libraries for many Machine Learning applications.
+Because of its speed, robustness, and ease of, it's one of the most widely-used libraries for many Machine Learning applications.
 
 Installation
 ~~~~~~~~~~~~
@@ -60,16 +60,16 @@ Through conda:
 
 	conda install scikit-learn
 
-scikit-learn also comes in shipped with Anaconda (mentioned above). For more installation instructions, refer to `this link <http://scikit-learn.org/stable/install.html>`_.
+scikit-learn also comes shipped with Anaconda (mentioned above). For more installation instructions, refer to `this link <http://scikit-learn.org/stable/install.html>`_.
 
 Example
 ~~~~~~~
 
 For this example, we train a simple classifier on the `Iris dataset <http://en.wikipedia.org/wiki/Iris_flower_data_set>`_, which comes bundled in with scikit-learn.
 
-The dataset takes four features of flowers: sepal length, sepal width, petal length and petal width, and classifies them into three flower species (labels): setosa, versicolor or virginica. The labels have been represented as numbers in the dataset: 0 (setosa), 1 (versicolor) and 2 (virginica).
+The dataset takes four features of flowers: sepal length, sepal width, petal length, and petal width, and classifies them into three flower species (labels): setosa, versicolor, or virginica. The labels have been represented as numbers in the dataset: 0 (setosa), 1 (versicolor), and 2 (virginica).
 
-We shuffle the Iris dataset, and divide it into separate training and testing sets: keeping the last 10 data points for testing and rest for training. We then train the classifier on the training set, and predict on the testing set.
+We shuffle the Iris dataset and divide it into separate training and testing sets, keeping the last 10 data points for testing and rest for training. We then train the classifier on the training set and predict on the testing set.
 
 .. code-block:: python
 
@@ -120,6 +120,6 @@ Since we're splitting randomly and the classifier trains on every iteration, the
 	[0 1 1 1 0 2 0 2 2 2]
 	100.0
 
-The first line contains the labels (i.e flower species) of the testing data as predicted by our classifier, and the second line contains the actual flower species as given in the dataset. We thus get an accuracy of 100% this time.
+The first line contains the labels (i.e. flower species) of the testing data as predicted by our classifier, and the second line contains the actual flower species as given in the dataset. We thus get an accuracy of 100% this time.
 
 More on scikit-learn can be read in the `documentation <http://scikit-learn.org/stable/user_guide.html>`_.

docs/scenarios/network.rst

@@ -12,8 +12,8 @@ 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
+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>`_.
 
 
@@ -30,8 +30,8 @@ message queuing without a message broker. The basic patterns for this are:
   remote procedure call and task distribution pattern.
 - publish-subscribe: connects a set of publishers to a set of subscribers.
   This is a data distribution pattern.
-- push-pull (or pipeline): connects nodes in a fan-out / fan-in pattern that
-  can have multiple steps, and loops. This is a parallel task distribution
+- push-pull (or pipeline): connects nodes in a fan-out/fan-in pattern that
+  can have multiple steps and loops. This is a parallel task distribution
   and collection pattern.
 
 For a quick start, read the `ZeroMQ guide <http://zguide.zeromq.org/page:all>`_.

docs/scenarios/scientific.rst

@@ -16,11 +16,11 @@ and performs well.
 
 Due to its high performance nature, scientific computing in Python often
 utilizes external libraries, typically written in faster languages (like C, or
-FORTRAN for matrix operations). The main libraries used are `NumPy`_, `SciPy`_
+Fortran for matrix operations). The main libraries used are `NumPy`_, `SciPy`_
 and `Matplotlib`_. Going into detail about these libraries is beyond the scope
 of the Python guide. However, a comprehensive introduction to the scientific
 Python ecosystem can be found in the `Python Scientific Lecture Notes
-<http://scipy-lectures.github.com/>`_
+<http://scipy-lectures.github.com/>`_.
 
 
 *****
@@ -35,7 +35,7 @@ which provides features of great interest to scientists. The `inline mode`
 allows graphics and plots to be displayed in the terminal (Qt based version).
 Moreover, the `notebook` mode supports literate programming and reproducible
 science generating a web-based Python notebook. This notebook allows you to
-store chunks of Python code along side the results and additional comments
+store chunks of Python code alongside the results and additional comments
 (HTML, LaTeX, Markdown). The notebook can then be shared and exported in various
 file formats.
 
@@ -48,7 +48,7 @@ NumPy
 -----
 
 `NumPy <http://numpy.scipy.org/>`_ is a low level library written in C (and
-FORTRAN) for high level mathematical functions. NumPy cleverly overcomes the
+Fortran) for high level mathematical functions. NumPy cleverly overcomes the
 problem of running slower algorithms on Python by using multidimensional arrays
 and functions that operate on arrays. Any algorithm can then be expressed as a
 function on arrays, allowing the algorithms to be run quickly.
@@ -57,7 +57,7 @@ NumPy is part of the SciPy project, and is released as a separate library so
 people who only need the basic requirements can use it without installing the
 rest of SciPy.
 
-NumPy is compatible with Python versions 2.4 through to 2.7.2 and 3.1+.
+NumPy is compatible with Python versions 2.4 through 2.7.2 and 3.1+.
 
 Numba
 -----
@@ -75,7 +75,7 @@ SciPy
 functions. SciPy uses NumPy arrays as the basic data structure, and comes
 with modules for various commonly used tasks in scientific programming,
 including linear algebra, integration (calculus), ordinary differential equation
-solving and signal processing.
+solving, and signal processing.
 
 Matplotlib
 ----------
@@ -84,7 +84,7 @@ Matplotlib
 library for creating interactive 2D and 3D plots that can also be saved as
 manuscript-quality figures. The API in many ways reflects that of `MATLAB
 <http://www.mathworks.com/products/matlab/>`_, easing transition of MATLAB
-users to Python. Many examples, along with the source code to re-create them,
+users to Python. Many examples, along with the source code to recreate them,
 are available in the `matplotlib gallery
 <http://matplotlib.sourceforge.net/gallery.html>`_.
 
@@ -92,10 +92,10 @@ Pandas
 ------
 
 `Pandas <http://pandas.pydata.org/>`_ is data manipulation library
-based on Numpy which provides many useful functions for accessing,
-indexing, merging and grouping data easily. The main data structure (DataFrame)
+based on NumPy which provides many useful functions for accessing,
+indexing, merging, and grouping data easily. The main data structure (DataFrame)
 is close to what could be found in the R statistical package; that is,
-heterogeneous data tables with name indexing, time series operations and
+heterogeneous data tables with name indexing, time series operations, and
 auto-alignment of data.
 
 Rpy2
@@ -112,7 +112,7 @@ PsychoPy
 
 `PsychoPy <http://www.psychopy.org/>`_ is a library for cognitive scientists
 allowing the creation of cognitive psychology and neuroscience experiments.
-The library handles presentation of stimuli, scripting of experimental design
+The library handles presentation of stimuli, scripting of experimental design,
 and data collection.
 
 
@@ -131,7 +131,7 @@ Unofficial Windows Binaries for Python Extension Packages
 
 Many people who do scientific computing are on Windows, yet many of the
 scientific computing packages are notoriously difficult to build and install on
-this platform. `Christoph Gohlke <http://www.lfd.uci.edu/~gohlke/pythonlibs/>`_
+this platform. `Christoph Gohlke <http://www.lfd.uci.edu/~gohlke/pythonlibs/>`_,
 however, has compiled a list of Windows binaries for many useful Python
 packages.  The list of packages has grown from a mainly scientific Python
 resource to a more general list. If you're on Windows, you may want to check it

docs/scenarios/scrape.rst

@@ -13,7 +13,7 @@ Web Scraping
 Web sites are written using HTML, which means that each web page is a
 structured document. Sometimes it would be great to obtain some data from
 them and preserve the structure while we're at it. Web sites don't always
-provide their data in comfortable formats such as ``csv`` or ``json``.
+provide their data in comfortable formats such as CSV or JSON.
 
 This is where web scraping comes in. Web scraping is the practice of using a
 computer program to sift through a web page and gather the data that you need
@@ -41,7 +41,7 @@ Let's start with the imports:
     import requests
 
 Next we will use ``requests.get`` to retrieve the web page with our data,
-parse it using the ``html`` module and save the results in ``tree``:
+parse it using the ``html`` module, and save the results in ``tree``:
 
 .. code-block:: python
 
@@ -62,10 +62,10 @@ HTML or XML documents. A good introduction to XPath is on
 There are also various tools for obtaining the XPath of elements such as
 FireBug for Firefox or the Chrome Inspector. If you're using Chrome, you
 can right click an element, choose 'Inspect element', highlight the code,
-right click again and choose 'Copy XPath'.
+right click again, and choose 'Copy XPath'.
 
 After a quick analysis, we see that in our page the data is contained in
-two elements - one is a div with title 'buyer-name' and the other is a
+two elements -- one is a div with title 'buyer-name' and the other is a
 span with class 'item-price':
 
 .. code-block:: html

docs/scenarios/serialization.rst

@@ -12,7 +12,7 @@ What is data serialization?
 
 Data serialization is the concept of converting structured data into a format
 that allows it to be shared or stored in such a way that its original
-structure to be recovered. In some cases, the secondary intention of data
+structure can be recovered. In some cases, the secondary intention of data
 serialization is to minimize the size of the serialized data which then
 minimizes disk space or bandwidth requirements.
 

docs/scenarios/speed.rst

@@ -200,8 +200,8 @@ These lines both need a remark:
 The `pyximport` module allows you to import :file:`*.pyx` files (e.g.,
 :file:`primesCy.pyx`) with the Cython-compiled version of the `primes`
 function. The `pyximport.install()` command allows the Python interpreter to
-start the Cython compiler directly to generate C-code, which is automatically
-compiled to a :file:`*.so` C-library. Cython is then able to import this
+start the Cython compiler directly to generate C code, which is automatically
+compiled to a :file:`*.so` C library. Cython is then able to import this
 library for you in your Python code, easily and efficiently. With the
 `time.time()` function you are able to compare the time between these 2
 different calls to find 500 prime numbers. On a standard notebook (dual core
@@ -214,7 +214,7 @@ AMD E-450 1.6 GHz), the measured values are:
     Python time: 0.0566 seconds
 
 
-And here the output of an embedded `ARM beaglebone <http://beagleboard.org/Products/BeagleBone>`_ machine:
+And here is the output of an embedded `ARM beaglebone <http://beagleboard.org/Products/BeagleBone>`_ machine:
 
 .. code-block:: console
 
@@ -253,7 +253,7 @@ available.
 
 The ProcessPoolExecutor works in the same way, except instead of using multiple
 threads for its workers, it will use multiple processes. This makes it possible
-to side-step the GIL, however because of the way things are passed to worker
+to side-step the GIL; however, because of the way things are passed to worker
 processes, only picklable objects can be executed and returned.
 
 Because of the way the GIL works, a good rule of thumb is to use a
@@ -264,7 +264,7 @@ executor when the task is computationally expensive.
 There are two main ways of executing things in parallel using the two
 Executors. One way is with the `map(func, iterables)` method. This works
 almost exactly like the builtin `map()` function, except it will execute
-everything in parallel. :
+everything in parallel.
 
 .. code-block:: python
 
@@ -304,7 +304,7 @@ result()
     the scheduled callable returns by default.
 exception()
     Return the exception raised by the call. If no exception was raised then
-    this returns `None`. Note that this will block just like `result()`.
+    this returns None. Note that this will block just like `result()`.
 add_done_callback(fn)
     Attach a callback function that will be executed (as `fn(future)`) when the
     scheduled callable returns.
@@ -357,14 +357,14 @@ futures provided have completed.
 For more information, on using the `concurrent.futures`_ module, consult the
 official documentation.
 
-Threading
+threading
 ---------
 
 The standard library comes with a `threading`_ module that allows a user to
 work with multiple threads manually.
 
 Running a function in another thread is as simple as passing a callable and
-it's arguments to `Thread`'s constructor and then calling `start()`:
+its arguments to `Thread`'s constructor and then calling `start()`:
 
 .. code-block:: python
 
@@ -399,7 +399,7 @@ there might be situations where two or more threads are trying to write to the
 same resource at the same time or where the output is dependent on the sequence
 or timing of certain events. This is called a `data race`_ or race condition.
 When this happens, the output will be garbled or you may encounter problems
-which are difficult to debug. A good example is this `stackoverflow post`_.
+which are difficult to debug. A good example is this `Stack Overflow post`_.
 
 The way this can be avoided is by using a `Lock`_ that each thread needs to
 acquire before writing to a shared resource. Locks can be acquired and released

docs/scenarios/web.rst

@@ -41,7 +41,7 @@ URL Routing
   be invoked
 
 Request and Response Objects
-  Encapsulate the information received from or sent to a user's browser
+  Encapsulates the information received from or sent to a user's browser
 
 Template Engine
   Allows for separating Python code implementing an application's logic from
@@ -105,14 +105,14 @@ It is a reliable, high-performance Python web framework for building large-scale
 app backends and microservices. Falcon encourages the REST architectural style of
 mapping URIs to resources, trying to do as little as possible while remaining highly effective.
 
-Falcon highlights four main focuses: speed, reliability, flexibility and debuggability.
+Falcon highlights four main focuses: speed, reliability, flexibility, and debuggability.
 It implements HTTP through "responders" such as ``on_get()``, ``on_put()``, etc.
 These responders receive intuitive request and response objects.
 
 Tornado
 --------
 
-`Tornado <http://www.tornadoweb.org/>`_ is an asyncronous web framework
+`Tornado <http://www.tornadoweb.org/>`_ is an asynchronous web framework
 for Python that has its own event loop. This allows it to natively support
 WebSockets, for example. Well-written Tornado applications are known to
 have excellent performance characteristics.
@@ -126,7 +126,7 @@ Pyramid
 focus on modularity. It comes with a small number of libraries ("batteries")
 built-in, and encourages users to extend its base functionality. A set of
 provided cookiecutter templates helps making new project decisions for users.
-It poweres one of the most important parts of python infrastucture
+It powers one of the most important parts of python infrastucture
 `PyPI <https://pypi.org/>`_.
 
 Pyramid does not have a large user base, unlike Django and Flask. It's a
@@ -136,11 +136,11 @@ applications today.
 Masonite
 --------
 
-`Masonite <https://docs.masoniteproject.com>`_ is a modern and developer centric, "batteries included", web framework. 
+`Masonite <https://docs.masoniteproject.com>`_ is a modern and developer centric, "batteries included", web framework.
 
 The Masonite framework follows the MVC (Model-View-Controller) architecture pattern and is heavily inspired by frameworks such as Rails and Laravel, so if you are coming to Python from a Ruby or PHP background then you will feel right at home!
 
-Masonite comes with a lot of functionality out of the box including a powerful IOC container with auto resolving dependency injection, craft command line tools and the Orator active record style ORM.
+Masonite comes with a lot of functionality out of the box including a powerful IOC container with auto resolving dependency injection, craft command line tools, and the Orator active record style ORM.
 
 Masonite is perfect for beginners or experienced developers alike and works hard to be fast and easy from install through to deployment. Try it once and you’ll fall in love.
 
@@ -155,7 +155,7 @@ Nginx
 -----
 
 `Nginx <http://nginx.org/>`_ (pronounced "engine-x") is a web server and
-reverse-proxy for HTTP, SMTP and other protocols. It is known for its
+reverse-proxy for HTTP, SMTP, and other protocols. It is known for its
 high performance, relative simplicity, and compatibility with many
 application servers (like WSGI servers). It also includes handy features
 like load-balancing, basic authentication, streaming, and others. Designed
@@ -177,9 +177,9 @@ servers and provide top performance [3]_.
 Gunicorn
 --------
 
-`Gunicorn <https://gunicorn.org/>`_ (Green Unicorn) is a pure-python WSGI
+`Gunicorn <https://gunicorn.org/>`_ (Green Unicorn) is a pure-Python WSGI
 server used to serve Python applications. Unlike other Python web servers,
-it has a thoughtful user-interface, and is extremely easy to use and
+it has a thoughtful user interface, and is extremely easy to use and
 configure.
 
 Gunicorn has sane and reasonable defaults for configurations. However, some
@@ -192,7 +192,7 @@ Gunicorn is the recommended choice for new Python web applications today.
 Waitress
 --------
 
-`Waitress <https://waitress.readthedocs.io>`_ is a pure-python WSGI server
+`Waitress <https://waitress.readthedocs.io>`_ is a pure-Python WSGI server
 that claims "very acceptable performance". Its documentation is not very
 detailed, but it does offer some nice functionality that Gunicorn doesn't have
 (e.g. HTTP request buffering).
@@ -207,13 +207,13 @@ uWSGI
 `uWSGI <https://uwsgi-docs.readthedocs.io>`_ is a full stack for building
 hosting services.  In addition to process management, process monitoring,
 and other functionality, uWSGI acts as an application server for various
-programming languages and protocols - including Python and WSGI. uWSGI can
+programming languages and protocols -- including Python and WSGI. uWSGI can
 either be run as a stand-alone web router, or be run behind a full web
 server (such as Nginx or Apache).  In the latter case, a web server can
 configure uWSGI and an application's operation over the
 `uwsgi protocol <https://uwsgi-docs.readthedocs.io/en/latest/Protocol.html>`_.
 uWSGI's web server support allows for dynamically configuring
-Python, passing environment variables and further tuning.  For full details,
+Python, passing environment variables, and further tuning.  For full details,
 see `uWSGI magic
 variables <https://uwsgi-docs.readthedocs.io/en/latest/Vars.html>`_.
 
@@ -275,7 +275,7 @@ Templating
 **********
 
 Most WSGI applications are responding to HTTP requests to serve content in HTML
-or other markup languages. Instead of generating directly textual content from
+or other markup languages. Instead of directly generating textual content from
 Python, the concept of separation of concerns advises us to use templates. A
 template engine manages a suite of template files, with a system of hierarchy
 and inclusion to avoid unnecessary repetition, and is in charge of rendering
@@ -313,10 +313,10 @@ Jinja2
 `Jinja2 <http://jinja.pocoo.org/>`_ is a very well-regarded template engine.
 
 It uses a text-based template language and can thus be used to generate any
-type markup, not just HTML. It allows customization of filters, tags, tests
+type of markup, not just HTML. It allows customization of filters, tags, tests,
 and globals. It features many improvements over Django's templating system.
 
-Here some important html tags in Jinja2:
+Here some important HTML tags in Jinja2:
 
 .. code-block:: html
 
@@ -336,7 +336,7 @@ Here some important html tags in Jinja2:
     {% endfor %}
 
 
-The next listings is an example of a web site in combination with the Tornado
+The next listings are an example of a web site in combination with the Tornado
 web server. Tornado is not very complicated to use.
 
 .. code-block:: python
@@ -434,12 +434,12 @@ engine implementation of the `Template Attribute Language (TAL) <https://en.wiki
 `TAL Expression Syntax (TALES) <https://chameleon.readthedocs.io/en/latest/reference.html#expressions-tales>`_,
 and `Macro Expansion TAL (Metal) <https://chameleon.readthedocs.io/en/latest/reference.html#macros-metal>`_ syntaxes.
 
-Chameleon is available for Python 2.5 and up (including 3.x and pypy), and
+Chameleon is available for Python 2.5 and up (including 3.x and PyPy), and
 is commonly used by the `Pyramid Framework <https://trypyramid.com/>`_.
 
 Page Templates add within your document structure special element attributes
 and text markup. Using a set of simple language constructs, you control the
-document flow, element repetition, text replacement and translation. Because
+document flow, element repetition, text replacement, and translation. Because
 of the attribute-based syntax, unrendered page templates are valid HTML and can
 be viewed in a browser and even edited in WYSIWYG editors. This can make
 round-trip collaboration with designers and prototyping with static files in a
@@ -493,7 +493,7 @@ Mako
 ----
 
 `Mako <http://www.makotemplates.org/>`_ is a template language that compiles to Python
-for maximum performance. Its syntax and api is borrowed from the best parts of other
+for maximum performance. Its syntax and API are borrowed from the best parts of other
 templating languages like Django and Jinja2 templates. It is the default template
 language included with the `Pylons and Pyramid <http://www.pylonsproject.org/>`_ web
 frameworks.

docs/scenarios/xml.rst

@@ -30,13 +30,13 @@ can be loaded like this:
     import untangle
     obj = untangle.parse('path/to/file.xml')
 
-and then you can get the child elements name like this:
+and then you can get the child element's name attribute like this:
 
 .. code-block:: python
 
     obj.root.child['name']
 
-untangle also supports loading XML from a string or an URL.
+untangle also supports loading XML from a string or a URL.
 
 
 *********
@@ -69,7 +69,7 @@ can be loaded into a Python dict like this:
     with open('path/to/file.xml') as fd:
         doc = xmltodict.parse(fd.read())
 
-and then you can access elements, attributes and values like this:
+and then you can access elements, attributes, and values like this:
 
 .. code-block:: python
 
@@ -79,5 +79,5 @@ and then you can access elements, attributes and values like this:
     doc['mydocument']['plus']['#text'] # == u'element as well'
 
 xmltodict also lets you roundtrip back to XML with the unparse function,
-has a streaming mode suitable for handling files that don't fit in memory
-and supports namespaces.
+has a streaming mode suitable for handling files that don't fit in memory,
+and supports XML namespaces.