First draft of manual

README.rst

@@ -1,17 +1,49 @@
 pytest-trio
 ===========
 
+.. image:: https://img.shields.io/badge/chat-join%20now-blue.svg
+   :target: https://gitter.im/python-trio/general
+   :alt: Join chatroom
+
+.. image:: https://img.shields.io/badge/docs-read%20now-blue.svg
+   :target: https://pytest-trio.readthedocs.io/en/latest/?badge=latest
+   :alt: Documentation Status
+
+.. image:: https://img.shields.io/pypi/v/pytest-trio.svg
+   :target: https://pypi.org/project/pytest-trio
+   :alt: Latest PyPi version
+
 .. image:: https://travis-ci.org/python-trio/pytest-trio.svg?branch=master
-    :target: https://travis-ci.org/python-trio/pytest-trio
+   :target: https://travis-ci.org/python-trio/pytest-trio
+   :alt: Automated test status (Linux and MacOS)
 
 .. image:: https://ci.appveyor.com/api/projects/status/aq0pklx7hanx031x?svg=true
-    :target: https://ci.appveyor.com/project/touilleMan/pytest-trio
+   :target: https://ci.appveyor.com/project/touilleMan/pytest-trio
+   :alt: Automated test status (Windows)
 
 .. image:: https://codecov.io/gh/python-trio/pytest-trio/branch/master/graph/badge.svg
-  :target: https://codecov.io/gh/python-trio/pytest-trio
+   :target: https://codecov.io/gh/python-trio/pytest-trio
+   :alt: Test coverage
+
+This is a pytest plugin to help you test projects that use `Trio
+<https://trio.readthedocs.io/>`__, a friendly library for concurrency
+and async I/O in Python. For an overview of features, see our `manual
+<https://pytest-trio.readthedocs.io>`__, or jump straight to the
+`quickstart guide
+<https://pytest-trio.readthedocs.io/en/latest/quickstart.html>`__.
+
+
+Vital statistics
+----------------
+
+**Documentation:** https://pytest-trio.readthedocs.io
 
-Welcome to `pytest-trio <https://github.com/python-trio/pytest-trio>`__!
+**Bug tracker and source code:**
+https://github.com/python-trio/pytest-trio
 
-Pytest plugin for trio
+**License:** MIT or Apache 2, your choice.
 
-License: Your choice of MIT or Apache License 2.0
+**Code of conduct:** Contributors are requested to follow our `code of
+conduct
+<https://github.com/python-trio/pytest-trio/blob/master/CODE_OF_CONDUCT.md>`__
+in all project spaces.

docs/source/history.rst

@@ -5,7 +5,27 @@ Release history
 
 .. towncrier release notes start
 
-Pytest_Trio 0.4.2 (2018-06-29)
+pytest-trio 0.5.0 (????-??-??)
+------------------------------
+
+This is a major release, including a rewrite of large portions of the
+internals. We believe it should be backwards compatible with existing
+projects, but major new features include:
+
+* "trio mode": no more writing ``@pytest.mark.trio`` everywhere!
+* it's now safe to use nurseries inside fixtures (`#55
+  <https://github.com/python-trio/pytest-trio/issues/55>`__)
+* new ``@trio_fixture`` decorator to explicitly mark a fixture as a
+  trio fixture
+* a number of easy-to-make mistakes are now caught and raise
+  informative errors
+* the :data:`nursery` fixture is now 87% more magical
+
+For more details, see the manual. Oh right, speaking of which: we
+finally have a manual! You should read it.
+
+
+pytest-trio 0.4.2 (2018-06-29)
 ------------------------------
 
 Features
@@ -16,20 +36,20 @@ Features
   using Trio. (`#42 <https://github.com/python-trio/pytest-trio/issues/42>`__)
 
 
-Pytest_Trio 0.4.1 (2018-04-14)
+pytest-trio 0.4.1 (2018-04-14)
 ------------------------------
 
 No significant changes.
 
 
-Pytest_Trio 0.4.0 (2018-04-14)
+pytest-trio 0.4.0 (2018-04-14)
 ------------------------------
 
 - Fix compatibility with trio 0.4.0 (`#25
   <https://github.com/python-trio/pytest-trio/pull/36>`__)
 
 
-Pytest_Trio 0.3.0 (2018-01-03)
+pytest-trio 0.3.0 (2018-01-03)
 ------------------------------
 
 Features
@@ -39,7 +59,7 @@ Features
   <https://github.com/python-trio/pytest-trio/issues/25>`__)
 
 
-Pytest_Trio 0.2.0 (2017-12-15)
+pytest-trio 0.2.0 (2017-12-15)
 ------------------------------
 
 - Heavy improvements, add async yield fixture, fix bugs, add tests etc. (`#17
@@ -53,14 +73,14 @@ Deprecations and Removals
   <https://github.com/python-trio/pytest-trio/issues/15>`__)
 
 
-Pytest_Trio 0.1.1 (2017-12-08)
+pytest-trio 0.1.1 (2017-12-08)
 ------------------------------
 
 Disable intersphinx for trio (cause crash in CI for the moment due to 404
 in readthedoc).
 
 
-Pytest_Trio 0.1.0 (2017-12-08)
+pytest-trio 0.1.0 (2017-12-08)
 ------------------------------
 
 Initial release.

docs/source/index.rst

@@ -8,9 +8,64 @@
 pytest-trio: Pytest plugin for trio
 ===================================
 
+This is a pytest plugin to help you test projects that use `Trio
+<https://trio.readthedocs.io/>`__, a friendly library for concurrency
+and async I/O in Python. Features include:
+
+* Async tests without the boilerplate: just write ``async def
+  test_whatever(): ...``.
+
+* Useful fixtures included: use :data:`autojump_clock` for easy
+  testing of code with timeouts, or :data:`nursery` to easily set up
+  background tasks.
+
+* Write your own async fixtures: set up an async database connection
+  or start a server inside a fixture, and then use it in your tests.
+
+* If you have multiple async fixtures, pytest-trio will even do
+  setup/teardown concurrently whenever possible. (Though honestly,
+  we're not sure whether this is a good idea or not and might remove
+  it in the future. If it makes your tests harder to debug, or
+  conversely provides you with big speedups, `please let us know
+  <https://github.com/python-trio/pytest-trio/issues/57>`__.)
+
+* Integration with the fabulous `Hypothesis
+  <https://hypothesis.works/>`__ library, so your async tests can use
+  property-based testing: just use ``@given`` like you're used to.
+
+* Support for testing projects that use Trio exclusively and want to
+  use pytest-trio everywhere, and also for testing projects that
+  support multiple async libraries and only want to enable
+  pytest-trio's features for a subset of their test suite.
+
+
+Vital statistics
+================
+
+* Install: ``pip install pytest-trio``
+
+* Documentation: https://pytest-trio.readthedocs.io
+
+* Issue tracker, source code: https://github.com/python-trio/pytest-trio
+
+* License: MIT or Apache 2, your choice
+
+* Contributor guide: https://trio.readthedocs.io/en/latest/contributing.html
+
+* Code of conduct: Contributors are requested to follow our `code of
+  conduct
+  <https://trio.readthedocs.io/en/latest/code-of-conduct.html>`__ in
+  all project spaces.
+
 .. toctree::
    :maxdepth: 2
 
+   quickstart.rst
+   reference.rst
+
+.. toctree::
+   :maxdepth: 1
+
    history.rst
 
 ====================