Merge pull request #862 from Zac-HD/various

Various cross-references in tests and installation advice

docs/scenarios/ci.rst

@@ -3,6 +3,9 @@ Continuous Integration
 
 .. image:: https://farm5.staticflickr.com/4173/33907150594_9abba7ad0a_k_d.jpg
 
+.. note::
+    For advice on writing your tests, see :doc:`writing/tests`.
+
 Why?
 ----
 

docs/starting/install/linux.rst

@@ -5,6 +5,9 @@ Installing Python 2 on Linux
 
 .. image:: https://farm5.staticflickr.com/4268/34435688560_4cc2a7bcbb_k_d.jpg
 
+.. note::
+    Check out our :ref:`guide for installing Python 3 on Linux<install3-linux>`.
+
 The latest versions of CentOS, Red Hat Enterprise Linux (RHEL) and Ubuntu
 **come with Python 2.7 out of the box**.
 

docs/starting/install/win.rst

@@ -5,6 +5,9 @@ Installing Python 2 on Windows
 
 .. image:: https://farm5.staticflickr.com/4268/34435688560_4cc2a7bcbb_k_d.jpg
 
+.. note::
+    Check out our :ref:`guide for installing Python 3 on Windows<install3-windows>`.
+
 First, download the `latest version <https://www.python.org/ftp/python/2.7.14/python-2.7.14.msi>`_
 of Python 2.7 from the official website. If you want to be sure you are installing a fully
 up-to-date version, click the Downloads > Windows link from the home page of the
@@ -50,24 +53,22 @@ makes it much easier for you to use other third-party Python libraries.
 Setuptools + Pip
 ----------------
 
-The most crucial third-party Python software of all is Setuptools, which
+The two most crucial third-party Python packages are `setuptools <https://pypi.python.org/pypi/setuptools>`_ and `pip <https://pip.pypa.io/en/stable/>`_.
-extends the packaging and installation facilities provided by the distutils in
-the standard library. Once you add Setuptools to your Python system you can
-download and install any compliant Python software product with a single
-command. It also enables you to add this network installation capability to
-your own Python software with very little work.
 
-To obtain the latest version of Setuptools for Windows, run the Python script
+Once installed, you can download, install and uninstall any compliant Python software
-available here: `ez_setup.py <https://bootstrap.pypa.io/ez_setup.py>`_
+product with a single command. It also enables you to add this network installation
+capability to your own Python software with very little work.
 
+Python 2.7.9 and later (on the python2 series), and Python 3.4 and later include
+pip by default.
 
-You'll now have a new command available to you: **easy_install**. It is
+To see if pip is installed, open a command prompt and run
-considered by many to be deprecated, so we will install its replacement:
-**pip**. Pip allows for uninstallation of packages, and is actively maintained,
-unlike easy_install.
 
-To install pip, run the Python script available here:
+.. code-block:: console
-`get-pip.py <https://raw.github.com/pypa/pip/master/contrib/get-pip.py>`_
+
+    $ command -v pip
+
+To install pip, `follow the official pip installation guide <https://pip.pypa.io/en/latest/installing/>`_ - this will automatically install the latest version of setuptools.
 
 
 Virtual Environments

docs/starting/install3/win.rst

@@ -64,24 +64,14 @@ This will launch the Python 3 interpreter.
 Setuptools + Pip
 ----------------
 
-The most crucial third-party Python software of all is Setuptools, which
+The two most crucial third-party Python packages are `setuptools <https://pypi.python.org/pypi/setuptools>`_ and `pip <https://pip.pypa.io/en/stable/>`_,
-extends the packaging and installation facilities provided by the distutils in
+which let you download, install and uninstall any compliant Python software
-the standard library. Once you add Setuptools to your Python system you can
+product with a single command. It also enables you to add this network installation
-download and install any compliant Python software product with a single
+capability to your own Python software with very little work.
-command. It also enables you to add this network installation capability to
-your own Python software with very little work.
 
-To obtain the latest version of Setuptools for Windows, run the Python script
+All supported versions of Python 3 include pip, so just make sure it's up to date::
-available here: `ez_setup.py <https://bootstrap.pypa.io/ez_setup.py>`_
 
-
+    python -m pip install -U pip
-You'll now have a new command available to you: **easy_install**. It is
-considered by many to be deprecated, so we will install its replacement:
-**pip**. Pip allows for uninstallation of packages, and is actively maintained,
-unlike easy_install.
-
-To install pip, run the Python script available here:
-`get-pip.py <https://raw.github.com/pypa/pip/master/contrib/get-pip.py>`_
 
 
 Pipenv & Virtual Environments

docs/starting/installation.rst

@@ -24,8 +24,8 @@ Installation Guides
 These guides go over the proper installation of :ref:`Python <which-python>`
 for development purposes, as well as setuptools, pip and virtualenv.
 
-  Python 3 Installation Guides
+Python 3 Installation Guides
-  ////////////////////////////
+////////////////////////////
 
 - :ref:`Python 3 on MacOS <install3-osx>`.
 - :ref:`Python 3 on Windows <install3-windows>`.

docs/starting/which-python.rst

@@ -58,7 +58,9 @@ It is possible to `write code that works on Python 2.6, 2.7, and Python 3
 <https://docs.python.org/3/howto/pyporting.html>`_. This
 ranges from trivial to hard depending upon the kind of software
 you are writing; if you're a beginner there are far more important things to
-worry about.
+worry about.  Note that Python 2.6 is end-of-life upstream, so you shouldn't
+try to write 2.6-compatible code unless you're being paid specifically to
+do that.
 
 Implementations
 ~~~~~~~~~~~~~~~

docs/writing/structure.rst

@@ -174,6 +174,8 @@ Test Suite
 ::::::::::
 
 
+*For advice on writing your tests, see :doc:`writing/tests`.*
+
 .. csv-table::
    :widths: 20, 40
 

docs/writing/tests.rst

@@ -190,21 +190,38 @@ the unittest module!
     `py.test <https://docs.pytest.org/en/latest/>`_
 
 
-Nose
+Hypothesis
-----
+----------
-
-nose extends unittest to make testing easier.
 
+Hypothesis is a library which lets you write tests that are parametrized by
+a source of examples.  It then generates simple and comprehensible examples
+that make your tests fail, letting you find more bugs with less work.
 
 .. code-block:: console
 
-    $ pip install nose
+    $ pip install hypothesis
 
-nose provides automatic test discovery to save you the hassle of manually
+For example, testing lists of floats will try many examples, but report the
-creating test suites. It also provides numerous plugins for features such as
+minimal example of each bug (distinguished exception type and location):
-xUnit-compatible test output, coverage reporting, and test selection.
 
-    `nose <https://nose.readthedocs.io/en/latest/>`_
+.. code-block:: python
+
+    @given(lists(floats(allow_nan=False, allow_infinity=False), min_size=1))
+    def test_mean(xs):
+        mean = sum(xs) / len(xs)
+        assert min(xs) <= mean(xs) <= max(xs)
+
+.. code-block::
+
+    Falsifying example: test_mean(
+        xs=[1.7976321109618856e+308, 6.102390043022755e+303]
+    )
+
+Hypothesis is practical as well as very powerful, and will often find bugs
+that escaped all other forms of testing.  It integrates well with py.test,
+and has a strong focus on usability in both simple and advanced scenarios.
+
+    `hypothesis <https://hypothesis.readthedocs.io/en/latest/>`_
 
 
 tox