Write a new README.rst

README.rst

@@ -1,8 +1,66 @@
-This is a plugin to facilitate image comparison for
-`Matplotlib <http://www.matplotlib.org>`__ figures in pytest.
-
-For each figure to test, the reference image is subtracted from the
-generated image, and the RMS of the residual is compared to a
-user-specified tolerance. If the residual is too large, the test will
-fail (this is implemented using helper functions from
-``matplotlib.testing``).
+``pytest-mpl``
+==============
+
+``pytest-mpl`` is a `pytest <https://docs.pytest.org>`__ plugin to facilitate image comparison for `Matplotlib <http://www.matplotlib.org>`__ figures.
+
+For each figure to test, an image is generated and then subtracted from an existing reference image.
+If the RMS of the residual is larger than a user-specified tolerance, the test will fail.
+Alternatively, the generated image can be hashed and compared to an expected value.
+
+For more information, see the `pytest-mpl documentation <https://pytest-mpl.readthedocs.io>`__.
+
+Installation
+------------
+.. code-block:: bash
+
+   pip install pytest-mpl
+
+For detailed instructions, see the `installation guide <https://pytest-mpl.readthedocs.io/en/latest/installing.html>`__ in the ``pytest-mpl`` docs.
+
+Usage
+-----
+First, write test functions that create a figure.
+These image comparison tests are decorated with ``@pytest.mark.mpl_image_compare`` and return the figure for testing:
+
+.. code-block:: python
+
+   import matplotlib.pyplot as plt
+   import pytest
+
+   @pytest.mark.mpl_image_compare
+   def test_plot():
+       fig, ax = plt.subplots()
+       ax.plot([1, 2])
+       return fig
+
+Then, generate reference images by running the test suite with the ``--mpl-generate-path`` option:
+
+.. code-block:: bash
+
+   pytest --mpl-generate-path=baseline
+
+Then, run the test suite as usual, but pass ``--mpl`` to compare the returned figures to the reference images:
+
+.. code-block:: bash
+
+   pytest --mpl
+
+By also passing ``--mpl-generate-summary=html``, a summary of the image comparison results will be generated in HTML format:
+
++---------------+---------------+---------------+
+| |html all|    | |html filter| | |html result| |
++---------------+---------------+---------------+
+
+For more information on how to configure and use ``pytest-mpl``, see the `pytest-mpl documentation <https://pytest-mpl.readthedocs.io>`__.
+
+Contributing
+------------
+``pytest-mpl`` is a community project maintained for and by its users.
+There are many ways you can help!
+
+- Report a bug or request a feature `on GitHub <https://github.com/matplotlib/pytest-mpl/issues>`__
+- Improve the documentation or code
+
+.. |html all| image:: docs/images/html_all.png
+.. |html filter| image:: docs/images/html_filter.png
+.. |html result| image:: docs/images/html_result.png