Add test discovery config instruction to tutorial chapter (docs) (#446)

Addresses issue #67

Use code-block directive for code blocks

Author: bittner

docs/faq.rst

@@ -18,30 +18,44 @@ How can I make sure that all my tests run with a specific locale?
 
 Create a `pytest fixture <http://pytest.org/latest/fixture.html>`_ that is
 automatically run before each test case. To run all tests with the english
-locale, put the following code in your project's `conftest.py
-<http://pytest.org/latest/plugins.html>`_ file::
+locale, put the following code in your project's `conftest.py`_ file:
+
+.. code-block:: python
 
     from django.utils.translation import activate
 
     @pytest.fixture(autouse=True)
     def set_default_language():
         activate('en')
 
+.. _conftest.py: http://docs.pytest.org/en/latest/plugins.html
+
 .. _faq-tests-not-being-picked-up:
 
-My tests are not being found. Why not?
--------------------------------------------------------------------------------------
- By default, pytest looks for tests in files named ``test_*.py`` (note that
- this is not the same as ``test*.py``).  If you have your tests in files with
- other names, they will not be collected. It is common to put tests under
- ``app_directory/tests/views.py``. To find those tests, create a ``pytest.ini``
- file in your project root with the contents::
+My tests are not being found. Why?
+----------------------------------
+
+By default, pytest looks for tests in files named ``test_*.py`` (note that
+this is not the same as ``test*.py``) and ``*_test.py``.  If you have your
+tests in files with other names, they will not be collected.  Note that
+Django's ``startapp`` manage command creates an ``app_dir/tests.py`` file.
+Also, it is common to put tests under ``app_dir/tests/views.py``, etc.
+
+To find those tests, create a ``pytest.ini`` file in your project root and add
+an appropriate ``python_files`` line to it:
+
+.. code-block:: ini
 
     [pytest]
-    python_files=*.py
+    python_files = tests.py test_*.py *_tests.py
+
+See the `related pytest docs`_ for more details.
 
-When debugging test collection problems, the ``--collectonly`` flag and ``-rs``
-(report skipped tests) can be helpful.
+When debugging test collection problems, the ``--collectonly`` flag and
+``-rs`` (report skipped tests) can be helpful.
+
+.. _related pytest docs:
+    http://docs.pytest.org/en/latest/example/pythoncollection.html#changing-naming-conventions
 
 Does pytest-django work with the pytest-xdist plugin?
 -----------------------------------------------------
@@ -58,7 +72,9 @@ How can I use ``manage.py test`` with pytest-django?
 
 pytest-django is designed to work with the ``pytest`` command, but if you
 really need integration with ``manage.py test``, you can create a simple
-test runner like this::
+test runner like this:
+
+.. code-block:: python
 
     class PytestTestRunner(object):
         """Runs pytest to discover and run tests."""
@@ -90,11 +106,15 @@ test runner like this::
             argv.extend(test_labels)
             return pytest.main(argv)
 
-Add the path to this class in your Django settings::
+Add the path to this class in your Django settings:
+
+.. code-block:: python
 
     TEST_RUNNER = 'my_project.runner.PytestTestRunner'
 
-Usage::
+Usage:
+
+.. code-block:: bash
 
     ./manage.py test <django args> -- <pytest args>
 
@@ -106,7 +126,9 @@ variables or the ``--settings`` command line option.
 How can I give database access to all my tests without the `django_db` marker?
 ------------------------------------------------------------------------------
 
-Create an autouse fixture and put it in `conftest.py` in your project root::
+Create an autouse fixture and put it in ``conftest.py`` in your project root:
+
+.. code-block:: python
 
     @pytest.fixture(autouse=True)
     def enable_db_access_for_all_tests(db):
@@ -115,11 +137,14 @@ Create an autouse fixture and put it in `conftest.py` in your project root::
 How/where can I get help with pytest/pytest-django?
 ---------------------------------------------------
 
-Usage questions can be asked on StackOverflow with the `pytest tag
-<http://stackoverflow.com/search?q=pytest>`_.
+Usage questions can be asked on StackOverflow with the `pytest tag`_.
 
 If you think you've found a bug or something that is wrong in the
-documentation, feel free to `open an issue on the Github project for
-pytest-django <https://github.com/pytest-dev/pytest-django/issues/>`_.
+documentation, feel free to `open an issue on the GitHub project`_ for
+pytest-django.
 
 Direct help can be found in the #pylib IRC channel on irc.freenode.org.
+
+.. _pytest tag: http://stackoverflow.com/search?q=pytest
+.. _open an issue on the GitHub project:
+    https://github.com/pytest-dev/pytest-django/issues/

docs/index.rst

@@ -1,7 +1,24 @@
-Welcome to pytest-django's documentation!
-=========================================
+===========================
+pytest-django Documentation
+===========================
 
-pytest-django is a plugin for `pytest <http://pytest.org/>`_ that provides a set of useful tools for testing `Django <http://www.djangoproject.com/>`_ applications and projects.
+pytest-django is a plugin for `pytest`_ that provides a set of useful tools
+for testing `Django`_ applications and projects.
+
+.. _pytest: http://pytest.org/
+.. _Django: https://www.djangoproject.com/
+
+Quick Start
+===========
+
+1. ``pip install pytest-django``
+2. Make sure ``DJANGO_SETTINGS_MODULE`` is defined and and run tests with the ``pytest`` command.
+3. (Optional) If you want tests of Django's default application layout be discovered (``tests.py``),
+   if you put your tests under a ``tests/`` directory , or your files are not named ``test_FOO.py``,
+   see the FAQ at :ref:`faq-tests-not-being-picked-up`.
+
+Table of Contents
+=================
 
 .. toctree::
    :maxdepth: 3
@@ -21,25 +38,24 @@ Why would I use this instead of Django's manage.py test command?
 
 Running the test suite with pytest offers some features that are not present in Django's standard test mechanism:
 
- * Less boilerplate: no need to import unittest, create a subclass with methods. Just write tests as regular functions.
- * `Manage test dependencies with fixtures <http://pytest.org/latest/fixture.html>`_
- * Database re-use: no need to re-create the test database for every test run.
- * Run tests in multiple processes for increased speed
- * There are a lot of other nice plugins available for pytest.
- * Easy switching: Existing unittest-style tests will still work without any modifications.
+* Less boilerplate: no need to import unittest, create a subclass with methods. Just write tests as regular functions.
+* `Manage test dependencies with fixtures`_.
+* Database re-use: no need to re-create the test database for every test run.
+* Run tests in multiple processes for increased speed.
+* There are a lot of other nice plugins available for pytest.
+* Easy switching: Existing unittest-style tests will still work without any modifications.
 
-See the `pytest documentation <http://pytest.org/latest/>`_ for more information on pytest.
-
-Quick Start
-===========
-1. ``pip install pytest-django``
-2. Make sure ``DJANGO_SETTINGS_MODULE`` is defined and and run tests with the ``pytest`` command.
-3. (Optionally) If you put your tests under a tests directory (the standard Django application layout), and your files are not named ``test_FOO.py``, see the FAQ :ref:`faq-tests-not-being-picked-up`.
+See the `pytest documentation`_ for more information on pytest.
 
+.. _Manage test dependencies with fixtures: http://docs.pytest.org/en/latest/fixture.html
+.. _pytest documentation: http://docs.pytest.org/
 
 Bugs? Feature suggestions?
-============================
-Report issues and feature requests at the `github issue tracker <http://github.com/pytest-dev/pytest-django/issues>`_.
+==========================
+
+Report issues and feature requests at the `GitHub issue tracker`_.
+
+.. _GitHub issue tracker: http://github.com/pytest-dev/pytest-django/issues
 
 Indices and tables
 ==================

docs/tutorial.rst

@@ -29,7 +29,9 @@ Step 1: Installation
 
 pytest-django can be obtained directly from `PyPI
 <http://pypi.python.org/pypi/pytest-django>`_, and can be installed with
-``pip``::
+``pip``:
+
+.. code-block:: bash
 
     pip install pytest-django
 
@@ -41,23 +43,37 @@ Step 2: Point pytest to your Django settings
 --------------------------------------------
 
 You need to tell pytest which Django settings that should be used for test
-runs. The easiest way to achieve this is to create a pytest configuration file with this information.
+runs. The easiest way to achieve this is to create a pytest configuration file
+with this information.
+
+Create a file called ``pytest.ini`` in your project root directory that
+contains:
 
-Create a file called ``pytest.ini`` in your project root directory that contains::
+.. code-block:: ini
 
     [pytest]
-    DJANGO_SETTINGS_MODULE=yourproject.settings
+    DJANGO_SETTINGS_MODULE = yourproject.settings
 
 You can also specify your Django settings by setting the
 ``DJANGO_SETTINGS_MODULE`` environment variable or specifying the
-``--ds=yourproject.settings`` command line flag when running the tests. See the
-full documentation on :ref:`configuring_django_settings`.
+``--ds=yourproject.settings`` command line flag when running the tests.
+See the full documentation on :ref:`configuring_django_settings`.
+
+Optionally, also add the following line to the ``[pytest]`` section to
+instruct pytest to collect tests in Django's default app layouts, too.
+See the FAQ at :ref:`faq-tests-not-being-picked-up` for more infos.
+
+.. code-block:: ini
+
+    python_files = tests.py test_*.py *_tests.py
 
 Step 3: Run your test suite
 ---------------------------
 
 Tests are invoked directly with the ``pytest`` command, instead of ``manage.py
-test``, that you might be used to::
+test``, that you might be used to:
+
+.. code-block:: bash
 
     pytest
 
@@ -73,7 +89,7 @@ pytest-django also provides some :ref:`helpers` to make it easier to write
 Django tests.
 
 Consult the `pytest documentation <http://pytest.org/>`_ for more information
-in pytest itself.
+on pytest itself.
 
 Stuck? Need help?
 -----------------