Improve docs index

docs/source/conf.py

@@ -31,8 +31,12 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    'sphinx.ext.autosectionlabel',
 ]
 
+autosectionlabel_prefix_document = True
+autosectionlabel_maxdepth = 2
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 

docs/source/guide/fixtures.rst

@@ -1,3 +1,5 @@
+.. _fixtures:
+
 Fixtures
 ========
 

docs/source/guide/pyproject.toml.rst

@@ -1,3 +1,5 @@
+.. _pyproject:
+
 Configuring Ward in ``pyproject.toml``
 ========================================
 
@@ -8,7 +10,7 @@ You can configure Ward using the standard ``pyproject.toml`` configuration file,
 
 You don't need a ``pyproject.toml`` file to use Ward.
 
-If you do decide to use one, Ward will find read your ``pyproject.toml`` file and treat the values inside it as defaults.
+If you do decide to use one, Ward will find and read your ``pyproject.toml`` file, and treat the values inside it as defaults.
 
 If you pass an option via the command line that also appears in your ``pyproject.toml``, the option supplied via the command line takes priority.
 

docs/source/guide/writing_tests.rst

@@ -73,6 +73,8 @@ use the helper ``assert_{op}`` methods from ``ward.expect``.
 
 .. TODO: Make some notes on how this works.
 
+.. _parameterisation:
+
 Parameterised testing
 ---------------------
 
@@ -188,6 +190,8 @@ use ``with raises(<exc_type>) as <exc_object>``::
 Note that ``ex`` is only populated after the context manager exits, so
 be careful with your indentation.
 
+.. _async_tests:
+
 Testing `async` code
 --------------------
 

docs/source/index.rst

@@ -1,20 +1,47 @@
 Ward - A modern Python test framework
 =====================================
 
-Ward is a test framework for Python with a focus on productivity and readability. It is heavily inspired by `pytest`, but
-diverges from it in several areas.
+Ward is a modern test framework for Python with a focus on productivity and readability.
+
+Features
+--------
+* Describe your tests using strings instead of function names
+* Use plain ``assert`` statements, with no need to remember ``assert*`` method names
+* Beautiful output that focuses on readability
+* Supported on MacOS, Linux, and Windows
+* Manage test dependencies using a simple but powerful :ref:`fixture system <fixtures>`
+* Support for :ref:`testing async code<async_tests>`
+* :ref:`Parameterised testing <parameterisation>` allows you to run a single test on multiple inputs
+* Configurable with :ref:`pyproject.toml<pyproject>`, but works out-of-the-box with sensible defaults
+* Fast -- Ward's suite of ~250 tests completes in <0.3 seconds on my machine
 
 .. image:: ./_static/intro_screenshot.png
     :align: center
     :alt: An example output from Ward
 
 Installation
 ------------
-Run ``pip install ward``. Ward requires Python 3.6+ in order to run.
+Ward is available on PyPI, and can be installed with ``pip install ward`` (Python 3.6+ required).
 
 Usage
 -----
-You can run all tests in your current directory by just running ``ward`` with no arguments.
+
+Here's a simple example of a test written using Ward:
+
+.. code-block:: python
+
+    # file: test_example.py
+    from ward import test
+
+    @test("the list contains 42")
+    def _():
+        assert 42 in [-21, 42, 999]
+
+To run the test, simply run ``ward`` in your terminal, and Ward will let you know how it went:
+
+.. image:: ./_static/usage_example_screenshot.png
+    :align: center
+    :alt: An example test result output from Ward
 
 .. toctree::
     :maxdepth: 2