Repository: DistrictDataLabs/yellowbrick

Issue:
Documentation README
### Proposal

Develop a documentation contribution guideline modeled after [pandas](https://github.com/pandas-dev/pandas/blob/master/doc/README.rst)

Documentation is often seen as a safe place for new contributors to start, but Sphinx and reStructured text can be intimidating at first. The goal of the readme would be to creating an inviting document that gives a high level of how to build the docs, where to find rst documentation, how and when to use the `plot::` directive, and give some direction towards some concrete issues to tackle (ie the novice and doc tags in the issue list).

Relates to issues #353 , #354  and PR #446 


Discussion:
Thanks for adding this issue - I think it's especially important after #354 
This is an excellent proposal and I think would be very valuable to our contributors. After #720 we think this should work as follows:

- Create a `docs/README.md` that has limited instructions about how to build docs and install requirements, then points to the documentation for further instructions.
- Create a section in the contributor's guide for documentation that discusses all of the above. 
- Perhaps also do the same for tests?

Resolving patch:
diff --git a/yellowbrick/features/jointplot.py b/yellowbrick/features/jointplot.py
--- a/yellowbrick/features/jointplot.py
+++ b/yellowbrick/features/jointplot.py
@@ -58,7 +58,7 @@ class JointPlot(FeatureVisualizer):
     feature-to-target plots. For pairwise feature analysis, the ``columns`` argument can
     be used to specify the index of the two desired columns in ``X``. If ``y`` is also
     specified, the plot can be colored with a heatmap or by class. For feature-to-target
-    plots, the user can provide either ``X`` and ``y` as 1D vectors, or a ``columns``
+    plots, the user can provide either ``X`` and ``y`` as 1D vectors, or a ``columns``
     argument with an index to a single feature in ``X`` to be plotted against ``y``.
 
     Histograms can be included by setting the ``hist`` argument to ``True`` for a


Test patch:
diff --git a/tests/README.md b/tests/README.md
new file mode 100644
--- /dev/null
+++ b/tests/README.md
@@ -0,0 +1,94 @@
+# Yellowbrick Tests
+
+*Welcome to the Yellowbrick tests!*
+
+If you're looking for information about how to use Yellowbrick, for our contributor's guide, for examples and teaching resources, for answers to frequently asked questions, and more, please visit the latest version of our documentation at [www.scikit-yb.org](https://www.scikit-yb.org/). 
+
+## Running Yellowbrick Tests
+
+To run the tests locally, first install the tests-specific requirements with `pip` using the `requirements.txt` file in the `tests` directory:
+
+```
+$ pip install -r tests/requirements.txt
+```
+
+The required dependencies for the test suite include testing utilities and libraries such as `pandas` and `nltk` that are not included in the core dependencies.
+
+Tests can then be run as follows from the project `root`:
+
+```bash
+$ make test
+```
+
+The Makefile uses the `pytest` runner and testing suite as well as the coverage library. 
+
+## Adding a Test for Your Visualizer
+
+The `tests` package mirrors the yellowbrick package in structure and also contains several helper methods and base functionality. To add a test to your visualizer, find the corresponding file to add the test case, or create a new test file in the same place you added your code.
+
+### Visual Tests
+
+The primary test you should create is simply to test your visualizer from end to end and make sure that no exceptions occur. 
+
+Visual tests are notoriously difficult to create --- how do you test a visualization or figure? Moreover, testing scikit-learn models with real data can consume a lot of memory. To assist with this, we have two primary helpers, `VisualTestCase` and the `yellowbrick.datasets` module. 
+
+Leverage these helpers to create your unittest as follows:
+
+```python
+import pytest
+
+from tests.base import VisualTestCase
+from yellowbrick.datasets import load_occupancy
+
+
+class MyVisualizerTests(VisualTestCase):
+
+    def test_my_visualizer(self):
+        """
+        Test MyVisualizer on a real dataset
+        """
+        # Load the data using the Yellowbrick datasets module
+        X, y = load_occupancy()
+
+        try:
+            visualizer = MyVisualizer()
+            visualizer.fit(X)
+            visualizer.finalize()
+        except Exception as e:
+            pytest.fail("my visualizer didn't work")
+```
+
+### Image Comparison Tests
+
+Writing an image-based comparison test is only a little more difficult than the simple test case presented above. We have adapted `matplotlib`'s image comparison test utility into an easy to use assert method: `self.assert_images_similar(visualizer)`
+
+The main consideration is that you must specify the “baseline” (i.e. expected) image in the `tests/baseline_images/` folder structure.
+
+For example, let's say you create your unittest in `tests/test_regressor/test_myvisualizer.py` as follows:
+
+```python
+from tests.base import VisualTestCase
+...
+    def test_my_visualizer_output(self):
+        ...
+        visualizer = MyVisualizer()
+        visualizer.fit(X)
+        visualizer.finalize()
+        self.assert_images_similar(visualizer)
+```
+
+The first time this test is run, there will be no baseline image to compare against, so the test will fail. Alternatively, if you are making a correction to the existing test `test_my_visualizer_output`, and the correction modifies the resulting test image, the test may also fail to match the existing baseline image. The solution is to first run the tests, then copy the new output images to the correct subdirectory under source code revision control (with `git add`). When rerunning the tests, they should now pass!
+
+We have a helper script, `tests/images.py` to clean up and manage baseline images automatically. It is run using the ``python -m`` command to execute a module as main, and it takes as an argument the path to **your** test file. To copy the figures as above:
+
+```bash
+$ python -m tests.images tests/test_regressor/test_myvisualizer.py
+```
+
+This will move all related test images from `actual_images` to `baseline_images` on your behalf (note you'll have had to already run the tests at least once to generate the images). You can also clean up images from both actual and baseline as follows:
+
+```bash
+$ python -m tests.images -C tests/test_regressor/test_myvisualizer.py
+```
+
+This is useful particularly if you're stuck trying to get an image comparison to work. For more information on the images helper script, use `python -m tests.images --help`.