Merge pull request #1 from kennethreitz/master

update from main repo

CONTRIBUTING.md

@@ -6,6 +6,28 @@ see:
 
 http://docs.python-guide.org/en/latest/notes/contribute/
 
+How to test your changes
+------------------------
+
+The html version of this guide is built with [sphinx](http://www.sphinx-doc.org/en/stable/). You may test your revisions locally by having sphinx installed. You can do this easily with pip (as described in the link).
+
+``` bash
+pip install --user sphinx
+```
+
+Then navigate to the directory of the makefile and ```make build``` or ```make html```. Sphinx will then generate the html in a folder called _build/html
+
+After navigating to this folder, you can then use python's built in webserver to view your changes locally:
+
+``` bash
+python3 -m http.server
+```
+
+By default, http.server listens on every ip address bound on your host on port 8000. To bind to a specific one, say, localhost on port 8005:
+
+``` bash
+python3 -m http.server 8005 --bind 127.0.0.1
+```
 
 Style Guide
 -----------

docs/_templates/sidebarintro.html

@@ -20,6 +20,13 @@ <h3>Stay Informed</h3>
 
 <p><a href="http://tinyletter.com/kennethreitz">Join Mailing List</a>.</p>
 
+<h3>O'Reilly Book</h3>
+
+<p>This guide is now available in tangible book form!</p>
+
+<a href="https://www.amazon.com/Hitchhikers-Guide-Python-Practices-Development/dp/1491933178/ref=as_li_ss_il?ie=UTF8&linkCode=li2&tag=bookforkind-20&linkId=804806ebdacaf3b56567347f3afbdbca" target="_blank"><img border="0" src="https://ws-na.amazon-adsystem.com/widgets/q?_encoding=UTF8&ASIN=1491933178&Format=_SL160_&ID=AsinImage&MarketPlace=US&ServiceVersion=20070822&WS=1&tag=bookforkind-20" ></a><img src="//ir-na.amazon-adsystem.com/e/ir?t=bookforkind-20&l=li2&o=1&a=1491933178" width="1" height="1" border="0" alt="" style="border:none !important; margin:0px !important;" />
+
+<p>All proceeds are being directly donated to the <a href="https://djangogirls.org">DjangoGirls</a> organization.</p>
 
 <h3>Other Projects</h3>
 
@@ -53,7 +60,8 @@ <h3>Useful Links</h3>
 <h3>Translations</h3>
 <ul>
   <li><a href="http://docs.python-guide.org/en/latest/">English</a></li>
-  <li><a href="http://pythonguidecn.readthedocs.org/zh/latest/">Chinese</a></li>
-  <li><a href="http://python-guide-ja.readthedocs.org/en/latest/">Japanese</a></li>
-  <li><a href="http://python-guide-kr.readthedocs.org/ko/latest/">Korean</a></li>
-</ul>
+  <li><a href="https://python-guide-fr.readthedocs.io/fr/latest/">French</a></li>
+  <li><a href="https://pythonguidecn.readthedocs.io/zh/latest/">Chinese</a></li>
+  <li><a href="https://python-guide-ja.readthedocs.io/en/latest/">Japanese</a></li>
+  <li><a href="https://python-guide-kr.readthedocs.io/ko/latest/">Korean</a></li>
+</ul>

docs/_templates/sidebarlogo.html

@@ -19,7 +19,13 @@ <h3>Get Updates</h3>
 
 <p><a href="http://tinyletter.com/kennethreitz">Join Mailing List</a>.</p>
 
+<h3>O'Reilly Book</h3>
 
+<p>This guide is now available in tangible book form!</p>
+
+<a href="https://www.amazon.com/Hitchhikers-Guide-Python-Practices-Development/dp/1491933178/ref=as_li_ss_il?ie=UTF8&linkCode=li2&tag=bookforkind-20&linkId=804806ebdacaf3b56567347f3afbdbca" target="_blank"><img border="0" src="https://ws-na.amazon-adsystem.com/widgets/q?_encoding=UTF8&ASIN=1491933178&Format=_SL160_&ID=AsinImage&MarketPlace=US&ServiceVersion=20070822&WS=1&tag=bookforkind-20" ></a><img src="//ir-na.amazon-adsystem.com/e/ir?t=bookforkind-20&l=li2&o=1&a=1491933178" width="1" height="1" border="0" alt="" style="border:none !important; margin:0px !important;" />
+
+<p>All proceeds are being directly donated to the <a href="https://djangogirls.org">DjangoGirls</a> organization.</p>
 
 <h3>Other Projects</h3>
 
@@ -36,7 +42,8 @@ <h3>Other Projects</h3>
 <h3>Translations</h3>
 <ul>
   <li><a href="http://docs.python-guide.org/en/latest/">English</a></li>
-  <li><a href="http://pythonguidecn.readthedocs.org/zh/latest/">Chinese</a></li>
-  <li><a href="http://python-guide-ja.readthedocs.org/en/latest/">Japanese</a></li>
-  <li><a href="http://python-guide-kr.readthedocs.org/ko/latest/">Korean</a></li>
-</ul>
+  <li><a href="https://python-guide-fr.readthedocs.io/fr/latest/">French</a></li>
+  <li><a href="https://pythonguidecn.readthedocs.io/zh/latest/">Chinese</a></li>
+  <li><a href="https://python-guide-ja.readthedocs.io/en/latest/">Japanese</a></li>
+  <li><a href="https://python-guide-kr.readthedocs.io/ko/latest/">Korean</a></li>
+</ul>

docs/contents.rst.inc

@@ -64,6 +64,7 @@ different scenarios.
    scenarios/xml
    scenarios/json
    scenarios/crypto
+   scenarios/ml
    scenarios/clibs
 
 

docs/dev/env.rst

@@ -150,6 +150,15 @@ features can be brought to IntelliJ with the free
 versions of PyCharm: Professional Edition (Free 30-day trial) and Community
 Edition(Apache 2.0 License) with fewer features.
 
+Python (on Visual Studio Code)
+-----------------------------
+
+`Python for Visual Studio <https://marketplace.visualstudio.com/items?itemName=donjayamanne.python>`_ is an extension for the `Visual Studio Code IDE <https://code.visualstudio.com>`_.
+This is a free, light weight, open source IDE, with support for Mac, Windows, and Linux.
+Built using open source technologies such as Node.js and Python, with compelling features such as Intellisense (autocompletion), local and remote debugging, linting, and the like.
+
+MIT licensed.
+
 Enthought Canopy
 ----------------
 `Enthought Canopy <https://www.enthought.com/products/canopy/>`_ is a Python

docs/dev/virtualenvs.rst

@@ -8,8 +8,8 @@ projects in separate places, by creating virtual Python environments for them.
 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.
 
-For example, you can work on a project which requires Django 1.3 while also
-maintaining a project which requires Django 1.0.
+For example, you can work on a project which requires Django 1.10 while also
+maintaining a project which requires Django 1.8.
 
 virtualenv
 ----------
@@ -122,7 +122,7 @@ control by adding it to the ignore list.
 virtualenvwrapper
 -----------------
 
-`virtualenvwrapper <http://virtualenvwrapper.readthedocs.org/en/latest/index.html>`_
+`virtualenvwrapper <https://virtualenvwrapper.readthedocs.io/en/latest/index.html>`_
 provides a set of commands which makes working with virtual environments much
 more pleasant. It also places all your virtual environments in one place.
 
@@ -134,7 +134,7 @@ To install (make sure **virtualenv** is already installed):
   $ export WORKON_HOME=~/Envs
   $ source /usr/local/bin/virtualenvwrapper.sh
 
-(`Full virtualenvwrapper install instructions <http://virtualenvwrapper.readthedocs.org/en/latest/install.html>`_.)
+(`Full virtualenvwrapper install instructions <https://virtualenvwrapper.readthedocs.io/en/latest/install.html>`_.)
 
 For Windows, you can use the `virtualenvwrapper-win <https://github.com/davidmarble/virtualenvwrapper-win/>`_.
 
@@ -206,7 +206,7 @@ Other useful commands
 ``lssitepackages``
   Shows contents of :file:`site-packages` directory.
 
-`Full list of virtualenvwrapper commands <http://virtualenvwrapper.readthedocs.org/en/latest/command_ref.html>`_.
+`Full list of virtualenvwrapper commands <https://virtualenvwrapper.readthedocs.io/en/latest/command_ref.html>`_.
 
 virtualenv-burrito
 ------------------

docs/intro/learning.rst

@@ -38,7 +38,7 @@ without having to install Python locally.
 If you want a more traditional book, *Python For You and Me* is an excellent
 resource for learning all aspects of the language.
 
-    `Python for You and Me <http://pymbook.readthedocs.org/>`_
+    `Python for You and Me <https://pymbook.readthedocs.io/>`_
 
 Online Python Tutor
 ~~~~~~~~~~~~~~~~~~~

docs/intro/news.rst

@@ -47,3 +47,10 @@ Weekly Python Newsletter containing Python Articles, Projects, Videos, Tweets
 delivered in your inbox.  Keep Your Python Programming Skills Updated.
 
     `Import Python Weekly Newsletter <http://www.importpython.com/newsletter/>`_
+
+Awesome Python Newsletter
+~~~~~~~~~~~~~~~~~~~~
+
+A weekly overview of the most popular Python news, articles and packages.
+
+    `Awesome Python Newsletter <https://python.libhunt.com/newsletter>`_

docs/scenarios/admin.rst

@@ -190,7 +190,7 @@ Ansible
 `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.
+orchestration language and are written in YAML with Jinja2 for templating.
 
 Ansible supports Python versions 2.6 and 2.7 and can be installed via pip:
 
@@ -262,7 +262,7 @@ To create a simple cookbook the `knife <https://docs.chef.io/knife.html>`_ comma
 
 `Getting started with Chef <http://gettingstartedwithchef.com/first-steps-with-chef.html>`_ 
 is a good starting point for Chef Beginners and many community maintained cookbooks that can 
-serve as a good reference or tweaked to serve your infrustructure configuration needs can be 
+serve as a good reference or tweaked to serve your infrastructure configuration needs can be 
 found on the `Chef Supermarket <https://supermarket.chef.io/cookbooks>`_.
 
 - `Chef Documentation <https://docs.chef.io/>`_
@@ -378,5 +378,14 @@ Buildout is primarily used to download and set up dependencies in Python eggs
 format of the software being developed or deployed. Recipes for build tasks in any
 environment can be created, and many are already available.
 
-Buidout is written in Python.
+Shinken
+-------
+
+`Shinken <http://www.shinken-monitoring.org/>`_ is a modern, Nagios compatible
+monitoring framework written in Python. Its main goal is to give users a flexible
+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.

docs/scenarios/ci.rst

@@ -31,22 +31,11 @@ Buildbot
 automate the compile/test cycle to validate code changes.
 
 
-Mule
------
-
-`Mule <http://www.mulesoft.org/documentation/display/current/Mule+Fundamentals>`_
-is a lightweight integration platform that enables you to connect anything,
-anywhere. You can use Mule to intelligently manage message routing, data
-mapping, orchestration, reliability, security and scalability between nodes.
-Plug other systems and applications into Mule and let it handle all the
-communication between systems, enabling you to track and monitor everything
-that happens.
-
 
 Tox
 ---
 
-`tox <http://tox.readthedocs.org/en/latest/>`_ is an automation tool providing
+`tox <https://tox.readthedocs.io/en/latest/>`_ 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:

docs/scenarios/cli.rst

@@ -16,7 +16,7 @@ Some popular command-line applications include:
 * `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 <http://mercurial.selenic.com/>`_ - A distributed version control
+* `mercurial <https://www.mercurial-scm.org/>`_ - A distributed version control
   system primarily written in Python
 
 Clint
@@ -62,3 +62,13 @@ subcommands, output formatters, and other extensions. The framework is meant
 to be used to create multi-level commands such as subversion and git, where
 the main program handles some basic argument parsing and then invokes a
 sub-command to do the work.
+
+Cement
+------
+
+`Cement <http://builtoncement.com/>`_ is an advanced CLI Application Framework. 
+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. 

docs/scenarios/clibs.rst

@@ -4,7 +4,7 @@ Interfacing with C/C++ Libraries
 C Foreign Function Interface
 ----------------------------
 
-`CFFI <https://cffi.readthedocs.org/en/latest/>`_ provides a simple to use
+`CFFI <https://cffi.readthedocs.io/en/latest/>`_ provides a simple to use
 mechanism for interfacing with C from both CPython and PyPy. It supports two
 modes: an inline ABI compatibility mode (example provided below), which allows
 you to dynamically load and run functions from executable modules (essentially
@@ -39,7 +39,7 @@ types, such as structs and unions, and allows you to modify things such as
 padding and alignment, if needed. It can be a bit crufty to use, but in
 conjunction with the `struct <https://docs.python.org/3.5/library/struct.html>`_
 module, you are essentially provided full control over how your data types get
-translated into something something usable by a pure C(++) method.
+translated into something usable by a pure C(++) method.
 
 Struct Equivalents
 ~~~~~~~~~~~~~~~~~~

docs/scenarios/crypto.rst

@@ -6,7 +6,7 @@ Cryptography
 
 `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.2+ and PyPy.
+Python 2.6-2.7, Python 3.3+ and PyPy.
 
 
 Cryptography is divided into two layers of recipes and hazardous materials

docs/scenarios/db.rst

@@ -29,7 +29,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
-programatically, or exported to a number of useful data formats.
+programmatically, or exported to a number of useful data formats.
 
 .. code-block:: console
 
@@ -60,11 +60,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
-`model layer <https://peewee.readthedocs.org/en/latest/peewee/quickstart.html#model-definition>`_
+`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.org/en/latest/peewee/quickstart.html#retrieving-data>`_
+`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,
-there is a `collection of add-ons <https://peewee.readthedocs.org/en/latest/peewee/playhouse.html#playhouse>`_
+there is a `collection of add-ons <https://peewee.readthedocs.io/en/latest/peewee/playhouse.html#playhouse>`_
 available.
 
 PonyORM

docs/scenarios/gui.rst

@@ -28,7 +28,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.
-It is fully compatible with GTK+ 3. Here is a tutorial to get started with `Python GTK+ 3 Tutorial <http://python-gtk-3-tutorial.readthedocs.org/en/latest/>`_.
+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/>`_
 

docs/scenarios/imaging.rst

@@ -24,7 +24,7 @@ Installation
 
 Before installing Pillow, you'll have to install Pillow's prerequisites. Find
 the instructions for your platform in the
-`Pillow installation instructions <https://pillow.readthedocs.org/en/3.0.0/installation.html>`_.
+`Pillow installation instructions <https://pillow.readthedocs.io/en/3.0.0/installation.html>`_.
 
 After that, it's straightforward:
 
@@ -57,7 +57,7 @@ Example
     exif_data
 
 There are more examples of the Pillow library in the
-`Pillow tutorial <http://pillow.readthedocs.org/en/3.0.x/handbook/tutorial.html>`_.
+`Pillow tutorial <https://pillow.readthedocs.io/en/3.0.x/handbook/tutorial.html>`_.
 
 
 OpenSource Computer Vision
@@ -104,4 +104,4 @@ Example
 
 There are more Python-implemented examples of OpenCV in this `collection of
 tutorials
-<http://opencv-python-tutroals.readthedocs.org/en/latest/py_tutorials/py_tutorials.html>`_.
+<https://opencv-python-tutroals.readthedocs.io/en/latest/py_tutorials/py_tutorials.html>`_.

docs/scenarios/json.rst

@@ -47,7 +47,7 @@ simplejson
 
 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.org/en/latest/>`_ library is
+`simplejson <https://simplejson.readthedocs.io/en/latest/>`_ library is
 available via PyPI.
 
 simplejson mimics the json standard library. It is available so that developers