docs: point to stable versions, improve references in a few places

Author: bluetech

docs/conf.py

@@ -40,9 +40,9 @@
 
 intersphinx_mapping = {
     'python': ('https://docs.python.org/3', None),
-    'django': ('https://docs.djangoproject.com/en/dev/',
-               'https://docs.djangoproject.com/en/dev/_objects/'),
-    'pytest': ('https://docs.pytest.org/en/latest/', None),
+    'django': ('https://docs.djangoproject.com/en/stable/',
+               'https://docs.djangoproject.com/en/stable/_objects/'),
+    'pytest': ('https://docs.pytest.org/en/stable/', None),
 }
 
 

docs/configuring_django.rst

@@ -9,7 +9,7 @@ the tests.
 The environment variable ``DJANGO_SETTINGS_MODULE``
 ---------------------------------------------------
 
-Running the tests with DJANGO_SETTINGS_MODULE defined will find the
+Running the tests with ``DJANGO_SETTINGS_MODULE`` defined will find the
 Django settings the same way Django does by default.
 
 Example::

docs/database.rst

@@ -12,8 +12,8 @@ what code uses the database and catches any mistakes.
 Enabling database access in tests
 ---------------------------------
 
-You can use `pytest marks <https://pytest.org/en/latest/mark.html>`_ to
-tell ``pytest-django`` your test needs database access::
+You can use :ref:`pytest marks <pytest:mark>` to tell ``pytest-django`` your
+test needs database access::
 
    import pytest
 
@@ -24,10 +24,8 @@ tell ``pytest-django`` your test needs database access::
 
 It is also possible to mark all tests in a class or module at once.
 This demonstrates all the ways of marking, even though they overlap.
-Just one of these marks would have been sufficient.  See the `pytest
-documentation
-<https://pytest.org/en/latest/example/markers.html#marking-whole-classes-or-modules>`_
-for detail::
+Just one of these marks would have been sufficient.  See the :ref:`pytest
+documentation <pytest:scoped-marking>` for detail::
 
    import pytest
 
@@ -45,20 +43,18 @@ By default ``pytest-django`` will set up the Django databases the
 first time a test needs them.  Once setup the database is cached for
 used for all subsequent tests and rolls back transactions to isolate
 tests from each other.  This is the same way the standard Django
-`TestCase
-<https://docs.djangoproject.com/en/1.9/topics/testing/tools/#testcase>`_
-uses the database.  However ``pytest-django`` also caters for
-transaction test cases and allows you to keep the test databases
-configured across different test runs.
+:class:`~django.test.TestCase` uses the database.  However
+``pytest-django`` also caters for transaction test cases and allows
+you to keep the test databases configured across different test runs.
 
 
 Testing transactions
 --------------------
 
-Django itself has the ``TransactionTestCase`` which allows you to test
-transactions and will flush the database between tests to isolate
-them.  The downside of this is that these tests are much slower to
-set up due to the required flushing of the database.
+Django itself has the :class:`~django.test.TransactionTestCase` which
+allows you to test transactions and will flush the database between
+tests to isolate them.  The downside of this is that these tests are
+much slower to set up due to the required flushing of the database.
 ``pytest-django`` also supports this style of tests, which you can
 select using an argument to the ``django_db`` mark::
 
@@ -184,8 +180,9 @@ django_db_modify_db_settings
 
 .. fixture:: django_db_modify_db_settings
 
-This fixture allows modifying `django.conf.settings.DATABASES` just before the
-databases are configured.
+This fixture allows modifying
+`django.conf.settings.DATABASES <https://docs.djangoproject.com/en/stable/ref/settings/#databases>`_
+just before the databases are configured.
 
 If you need to customize the location of your test database, this is the
 fixture you want to override.

docs/faq.rst

@@ -16,9 +16,10 @@ for more information.
 How can I make sure that all my tests run with a specific locale?
 -----------------------------------------------------------------
 
-Create a `pytest fixture <https://pytest.org/en/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`_ file:
+Create a :ref:`pytest fixture <pytest:fixtures>` that is
+automatically run before each test case. To run all tests with the English
+locale, put the following code in your project's
+:ref:`conftest.py <pytest:plugins>` file:
 
 .. code-block:: python
 
@@ -28,8 +29,6 @@ locale, put the following code in your project's `conftest.py`_ file:
     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?
@@ -55,7 +54,7 @@ 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
+    http://docs.pytest.org/en/stable/example/pythoncollection.html#changing-naming-conventions
 
 Does pytest-django work with the pytest-xdist plugin?
 -----------------------------------------------------

docs/helpers.rst

@@ -16,11 +16,9 @@ All of Django's :py:class:`~django:django.test.TestCase`
 Markers
 -------
 
-``pytest-django`` registers and uses markers.  See the pytest documentation_
-on what marks are and for notes on using_ them.
-
-.. _documentation: https://pytest.org/en/latest/mark.html
-.. _using: https://pytest.org/en/latest/example/markers.html#marking-whole-classes-or-modules
+``pytest-django`` registers and uses markers.  See the pytest
+:ref:`documentation <pytest:mark>` on what marks are and for notes on
+:ref:`using <pytest:scoped-marking>` them.
 
 
 ``pytest.mark.django_db`` - request database access
@@ -32,7 +30,7 @@ This is used to mark a test function as requiring the database. It
 will ensure the database is set up correctly for the test. Each test
 will run in its own transaction which will be rolled back at the end
 of the test. This behavior is the same as Django's standard
-`django.test.TestCase`_ class.
+:class:`~django.test.TestCase` class.
 
 In order for a test to have access to the database it must either
 be marked using the ``django_db`` mark or request one of the ``db``,
@@ -44,9 +42,8 @@ test will fail when trying to access the database.
  The ``transaction`` argument will allow the test to use real transactions.
  With ``transaction=False`` (the default when not specified), transaction
  operations are noops during the test. This is the same behavior that
- `django.test.TestCase`_
- uses. When ``transaction=True``, the behavior will be the same as
- `django.test.TransactionTestCase`_
+ :class:`django.test.TestCase` uses. When ``transaction=True``, the behavior
+ will be the same as :class:`django.test.TransactionTestCase`.
 
 
 :type reset_sequences: bool
@@ -68,13 +65,10 @@ test will fail when trying to access the database.
 
 .. note:: Automatic usage with ``django.test.TestCase``.
 
- Test classes that subclass `django.test.TestCase`_ will have access to
+ Test classes that subclass :class:`django.test.TestCase` will have access to
  the database always to make them compatible with existing Django tests.
- Test classes that subclass Python's ``unittest.TestCase`` need to have the
- marker applied in order to access the database.
-
-.. _django.test.TestCase: https://docs.djangoproject.com/en/dev/topics/testing/overview/#testcase
-.. _django.test.TransactionTestCase: https://docs.djangoproject.com/en/dev/topics/testing/overview/#transactiontestcase
+ Test classes that subclass Python's :class:`unittest.TestCase` need to have
+ the marker applied in order to access the database.
 
 
 ``pytest.mark.urls`` - override the urlconf
@@ -119,16 +113,14 @@ Fixtures
 --------
 
 pytest-django provides some pytest fixtures to provide dependencies for tests.
-More information on fixtures is available in the `pytest documentation
-<https://pytest.org/en/latest/fixture.html>`_.
+More information on fixtures is available in the :ref:`pytest documentation
+<pytest:fixtures>`.
 
 
 ``rf`` - ``RequestFactory``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-An instance of a `django.test.RequestFactory`_
-
-.. _django.test.RequestFactory: https://docs.djangoproject.com/en/dev/topics/testing/advanced/#django.test.RequestFactory
+An instance of a :class:`django.test.RequestFactory`.
 
 Example
 """""""
@@ -145,9 +137,7 @@ Example
 ``client`` - ``django.test.Client``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-An instance of a `django.test.Client`_
-
-.. _django.test.Client: https://docs.djangoproject.com/en/dev/topics/testing/tools/#the-test-client
+An instance of a :class:`django.test.Client`.
 
 Example
 """""""
@@ -158,8 +148,9 @@ Example
         response = client.get('/')
         assert response.content == 'Foobar'
 
-To use `client` as an authenticated standard user, call its `force_login()` or
-`login()` method before accessing a URL:
+To use `client` as an authenticated standard user, call its
+:meth:`force_login() <django.test.Client.force_login>` or
+:meth:`login() <django.test.Client.login()>` method before accessing a URL:
 
 ::
 
@@ -178,7 +169,7 @@ To use `client` as an authenticated standard user, call its `force_login()` or
 ``admin_client`` - ``django.test.Client`` logged in as admin
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-An instance of a `django.test.Client`_, logged in as an admin user.
+An instance of a :class:`django.test.Client`, logged in as an admin user.
 
 Example
 """""""
@@ -208,7 +199,8 @@ Using the `admin_user` fixture will cause the test to automatically be marked fo
 ~~~~~~~~~~~~~~~~~~~~~
 
 A shortcut to the User model configured for use by the current Django project (aka the model referenced by
-`settings.AUTH_USER_MODEL`). Use this fixture to make pluggable apps testable regardless what User model is configured
+`settings.AUTH_USER_MODEL <https://docs.djangoproject.com/en/stable/ref/settings/#auth-user-model>`_).
+Use this fixture to make pluggable apps testable regardless what User model is configured
 in the containing Django project.
 
 Example
@@ -223,8 +215,9 @@ Example
 ``django_username_field``
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-This fixture extracts the field name used for the username on the user model, i.e. resolves to the current
-``settings.USERNAME_FIELD``. Use this fixture to make pluggable apps testable regardless what the username field
+This fixture extracts the field name used for the username on the user model, i.e.
+resolves to the user model's :attr:`~django.contrib.auth.models.CustomUser.USERNAME_FIELD`.
+Use this fixture to make pluggable apps testable regardless what the username field
 is configured to be in the containing Django project.
 
 ``db``
@@ -264,7 +257,7 @@ normally use the ``pytest.mark.django_db`` mark with ``transaction=True`` and ``
 
 This fixture runs a live Django server in a background thread.  The
 server's URL can be retrieved using the ``live_server.url`` attribute
-or by requesting it's string value: ``unicode(live_server)``.  You can
+or by requesting it's string value: ``str(live_server)``.  You can
 also directly concatenate a string to form a URL: ``live_server +
 '/foo``.
 
@@ -313,8 +306,8 @@ This fixture allows to check for an expected number of DB queries.
 If the assertion failed, the executed queries can be shown by using
 the verbose command line option.
 
-It wraps `django.test.utils.CaptureQueriesContext` and yields the wrapped
-CaptureQueriesContext instance.
+It wraps ``django.test.utils.CaptureQueriesContext`` and yields the wrapped
+``CaptureQueriesContext`` instance.
 
 Example usage::
 

docs/index.rst

@@ -39,14 +39,13 @@ 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`_.
+* :ref:`Manage test dependencies with fixtures <pytest:fixtures>`.
 * 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`_ 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?

docs/tutorial.rst

@@ -21,7 +21,7 @@ Talks, articles and blog posts
    John Costa
    <https://www.johnmcostaiii.net/post/2013-04-21-django-projects-to-django-apps-converting-the-unit-tests/>`_.
 
-For general information and tutorials on pytest, see the `pytest tutorial page <https://pytest.org/en/latest/getting-started.html>`_.
+For general information and tutorials on pytest, see the `pytest tutorial page <https://pytest.org/en/stable/getting-started.html>`_.
 
 
 Step 1: Installation

docs/usage.rst

@@ -20,7 +20,7 @@ the command line::
     pytest test_something.py a_directory
 
 See the `pytest documentation on Usage and invocations
-<https://pytest.org/en/latest/usage.html>`_ for more help on available parameters.
+<https://pytest.org/en/stable/usage.html>`_ for more help on available parameters.
 
 Additional command line options
 -------------------------------
@@ -51,6 +51,6 @@ is set to "foo", the test database with xdist will be "test_foo_gw0",
 "test_foo_gw1" etc.
 
 See the full documentation on `pytest-xdist
-<https://pytest.org/en/latest/xdist.html>`_ for more information. Among other
-features, pytest-xdist can distribute/coordinate test execution on remote
-machines.
+<https://github.com/pytest-dev/pytest-xdist/blob/master/README.rst>`_ for more
+information. Among other features, pytest-xdist can distribute/coordinate test
+execution on remote machines.