Merge pull request #8430 from evildmp/evolutionary-documentation-restructure

Renamed Install to Getting started; moved notes to index.

doc/en/_templates/globaltoc.html

@@ -2,7 +2,7 @@
 
 <ul>
   <li><a href="{{ pathto('index') }}">Home</a></li>
-  <li><a href="{{ pathto('getting-started') }}">Install</a></li>
+  <li><a href="{{ pathto('getting-started') }}">Get started</a></li>
   <li><a href="{{ pathto('contents') }}">Contents</a></li>
   <li><a href="{{ pathto('reference') }}">API Reference</a></li>
   <li><a href="{{ pathto('example/index') }}">Examples</a></li>

doc/en/assert.rst

@@ -1,5 +1,5 @@
 
-The writing and reporting of assertions in tests
+How to write and report assertions in tests
 ==================================================
 
 .. _`assertfeedback`:

doc/en/bash-completion.rst

@@ -1,8 +1,8 @@
 
 .. _bash_completion:
 
-Setting up bash completion
-==========================
+How to set up bash completion
+=============================
 
 When using bash as your shell, ``pytest`` can use argcomplete
 (https://argcomplete.readthedocs.io/) for auto-completion.

doc/en/capture.rst

@@ -1,7 +1,7 @@
 
 .. _`captures`:
 
-Capturing of the stdout/stderr output
+How to capture stdout/stderr output
 =========================================================
 
 Default stdout/stderr/stdin capturing behaviour

doc/en/existingtestsuite.rst

@@ -1,7 +1,7 @@
 .. _existingtestsuite:
 
-Using pytest with an existing test suite
-===========================================
+How to use pytest with an existing test suite
+==============================================
 
 Pytest can be used with most existing test suites, but its
 behavior differs from other test runners such as :ref:`nose <noseintegration>` or

doc/en/getting-started.rst

@@ -1,22 +1,14 @@
-Installation and Getting Started
+Get Started
 ===================================
 
-**Pythons**: Python 3.6, 3.7, 3.8, 3.9, PyPy3
-
-**Platforms**: Linux and Windows
-
-**PyPI package name**: `pytest <https://pypi.org/project/pytest/>`_
-
-**Documentation as PDF**: `download latest <https://media.readthedocs.org/pdf/pytest/latest/pytest.pdf>`_
-
-``pytest`` is a framework that makes building simple and scalable tests easy. Tests are expressive and readable—no boilerplate code required. Get started in minutes with a small unit test or complex functional test for your application or library.
-
 .. _`getstarted`:
 .. _`installation`:
 
 Install ``pytest``
 ----------------------------------------
 
+``pytest`` requires: Python 3.6, 3.7, 3.8, 3.9, or PyPy3.
+
 1. Run the following command in your command line:
 
 .. code-block:: bash
@@ -35,7 +27,7 @@ Install ``pytest``
 Create your first test
 ----------------------------------------------------------
 
-Create a simple test function with just four lines of code:
+Create a new file called ``test_sample.py``, containing a function, and a test:
 
 .. code-block:: python
 
@@ -47,7 +39,7 @@ Create a simple test function with just four lines of code:
     def test_answer():
         assert func(3) == 5
 
-That’s it. You can now execute the test function:
+The test
 
 .. code-block:: pytest
 

doc/en/index.rst

@@ -13,10 +13,19 @@ pytest: helps you write better programs
 
 .. module:: pytest
 
-The ``pytest`` framework makes it easy to write small tests, yet
-scales to support complex functional testing for applications and libraries.
+The ``pytest`` framework makes it easy to write small, readable tests, and can
+scale to support complex functional testing for applications and libraries.
 
-An example of a simple test:
+
+**Pythons**: ``pytest`` requires: Python 3.6, 3.7, 3.8, 3.9, or PyPy3.
+
+**PyPI package name**: `pytest <https://pypi.org/project/pytest/>`_
+
+**Documentation as PDF**: `download latest <https://media.readthedocs.org/pdf/pytest/latest/pytest.pdf>`_
+
+
+A quick example
+---------------
 
 .. code-block:: python
 
@@ -56,7 +65,7 @@ To execute it:
     ============================ 1 failed in 0.12s =============================
 
 Due to ``pytest``'s detailed assertion introspection, only plain ``assert`` statements are used.
-See :ref:`Getting Started <getstarted>` for more examples.
+See :ref:`Get started <getstarted>` for a basic introduction to using pytest.
 
 
 Features

doc/en/mark.rst

@@ -1,7 +1,7 @@
 .. _mark:
 
-Marking test functions with attributes
-======================================
+How to mark test functions with attributes
+===========================================
 
 By using the ``pytest.mark`` helper you can easily set
 metadata on your test functions. You can find the full list of builtin markers

doc/en/monkeypatch.rst

@@ -1,5 +1,5 @@
 
-Monkeypatching/mocking modules and environments
+How to monkeypatch/mock modules and environments
 ================================================================
 
 .. currentmodule:: _pytest.monkeypatch

doc/en/nose.rst

@@ -1,6 +1,6 @@
 .. _`noseintegration`:
 
-Running tests written for nose
+How to run tests written for nose
 =======================================
 
 ``pytest`` has basic support for running tests written for nose_.

doc/en/parametrize.rst

@@ -6,7 +6,7 @@
 
 .. _`parametrize-basics`:
 
-Parametrizing fixtures and test functions
+How to parametrize fixtures and test functions
 ==========================================================================
 
 pytest enables test parametrization at several levels:

doc/en/plugins.rst

@@ -2,8 +2,8 @@
 .. _`extplugins`:
 .. _`using plugins`:
 
-Installing and Using plugins
-============================
+How to install and use plugins
+===============================
 
 This section talks about installing and using third party plugins.
 For writing your own plugins, please refer to :ref:`writing-plugins`.

doc/en/skipping.rst

@@ -2,8 +2,8 @@
 
 .. _skipping:
 
-Skip and xfail: dealing with tests that cannot succeed
-======================================================
+How to use skip and xfail to deal with tests that cannot succeed
+=================================================================
 
 You can mark test functions that cannot be run on certain platforms
 or that you expect to fail so pytest can deal with them accordingly and

doc/en/tmpdir.rst

@@ -2,8 +2,8 @@
 .. _`tmpdir handling`:
 .. _tmpdir:
 
-Temporary directories and files
-================================================
+How to use temporary directories and files in tests
+===================================================
 
 The ``tmp_path`` fixture
 ------------------------

doc/en/usage.rst

@@ -1,7 +1,7 @@
 
 .. _usage:
 
-Usage and Invocations
+How to invoke pytest
 ==========================================