Merge pull request #882 from bluetech/docs-fixes

docs: some fixes/cleanups

Author: bluetech

docs/changelog.rst

@@ -656,7 +656,7 @@ bugs.
 The tests for pytest-django itself has been greatly improved, paving the
 way for easier additions of new and exciting features in the future!
 
-* Semantic version numbers will now be used for releases, see http://semver.org/.
+* Semantic version numbers will now be used for releases, see https://semver.org/.
 
 * Do not allow database access in tests by default.  Introduce
   ``pytest.mark.django_db`` to enable database access.
@@ -720,7 +720,7 @@ v1.1
 ----
 
 * The initial release of this fork from `Ben Firshman original project
-  <http://github.com/bfirsh/pytest_django>`__
+  <https://github.com/bfirsh/pytest_django>`__
 * Added documentation
 * Uploaded to PyPI for easy installation
 * Added the ``transaction_test_case`` decorator for tests that needs real transactions

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/contributing.rst

@@ -227,16 +227,16 @@ double cookie points. Seriously. You rock.
 
 .. _fork: https://github.com/pytest-dev/pytest-django
 .. _issue tracker: https://github.com/pytest-dev/pytest-django/issues
-.. _Sphinx: http://sphinx.pocoo.org/
-.. _PEP8: http://www.python.org/dev/peps/pep-0008/
-.. _GitHub : http://www.github.com
-.. _GitHub help : http://help.github.com
-.. _freenode : http://freenode.net/
+.. _Sphinx: https://www.sphinx-doc.org/
+.. _PEP8: https://www.python.org/dev/peps/pep-0008/
+.. _GitHub : https://www.github.com
+.. _GitHub help : https://help.github.com
+.. _freenode : https://freenode.net/
 .. _@andreaspelme : https://twitter.com/andreaspelme
-.. _pull request : http://help.github.com/send-pull-requests/
-.. _git : http://git-scm.com/
-.. _restructuredText: http://docutils.sourceforge.net/docs/ref/rst/introduction.html
+.. _pull request : https://help.github.com/send-pull-requests/
+.. _git : https://git-scm.com/
+.. _restructuredText: https://docutils.sourceforge.io/docs/ref/rst/introduction.html
 .. _django CMS: https://www.django-cms.org/
 .. _GitHub Actions: https://github.com/features/actions
 .. _pytest-django Actions: https://github.com/pytest-dev/pytest-django/actions
-.. _`subprocess section of coverage documentation`: http://nedbatchelder.com/code/coverage/subprocess.html
+.. _`subprocess section of coverage documentation`: https://coverage.readthedocs.io/en/latest/subprocess.html

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::
 
@@ -83,8 +79,8 @@ directly in ``pytest-django`` please get in touch, we are interested
 in eventually supporting this but unsure about simply following
 Django's approach.
 
-See `https://github.com/pytest-dev/pytest-django/pull/431` for an idea /
-discussion to approach this.
+See `pull request 431 <https://github.com/pytest-dev/pytest-django/pull/431>`_
+for an idea/discussion to approach this.
 
 ``--reuse-db`` - reuse the testing database between test runs
 --------------------------------------------------------------
@@ -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.
@@ -333,7 +330,7 @@ Put this into ``conftest.py``::
         conn.close()
 
 
-    @pytest.yield_fixture(scope='session')
+    @pytest.fixture(scope='session')
     def django_db_setup():
         from django.conf import settings
 

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
+    https://docs.pytest.org/en/stable/example/pythoncollection.html#changing-naming-conventions
 
 Does pytest-django work with the pytest-xdist plugin?
 -----------------------------------------------------
@@ -145,6 +144,6 @@ pytest-django.
 
 Direct help can be found in the #pylib IRC channel on irc.freenode.org.
 
-.. _pytest tag: http://stackoverflow.com/search?q=pytest
+.. _pytest tag: https://stackoverflow.com/search?q=pytest
 .. _open an issue on the GitHub project:
     https://github.com/pytest-dev/pytest-django/issues/

docs/helpers.rst

@@ -16,46 +16,43 @@ 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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. :py:function:: pytest.mark.django_db([transaction=False, reset_sequences=False]):
-
-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.
-
-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``,
-``transactional_db`` or ``django_db_reset_sequences`` fixtures.  Otherwise the
-test will fail when trying to access the database.
-
-:type transaction: bool
-:param transaction:
- 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`_
-
-
-:type reset_sequences: bool
-:param reset_sequences:
- The ``reset_sequences`` argument will ask to reset auto increment sequence
- values (e.g. primary keys) before running the test.  Defaults to
- ``False``.  Must be used together with ``transaction=True`` to have an
- effect.  Please be aware that not all databases support this feature.
- For details see :py:attr:`django.test.TransactionTestCase.reset_sequences`.
+.. py:function:: pytest.mark.django_db([transaction=False, reset_sequences=False])
+
+  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
+  :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``,
+  ``transactional_db`` or ``django_db_reset_sequences`` fixtures.  Otherwise the
+  test will fail when trying to access the database.
+
+  :type transaction: bool
+  :param transaction:
+    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
+    :class:`django.test.TestCase` uses. When ``transaction=True``, the behavior
+    will be the same as :class:`django.test.TransactionTestCase`.
+
+
+  :type reset_sequences: bool
+  :param reset_sequences:
+    The ``reset_sequences`` argument will ask to reset auto increment sequence
+    values (e.g. primary keys) before running the test.  Defaults to
+    ``False``.  Must be used together with ``transaction=True`` to have an
+    effect.  Please be aware that not all databases support this feature.
+    For details see :py:attr:`django.test.TransactionTestCase.reset_sequences`.
 
 .. note::
 
@@ -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::