Update documentation on pyqt4v2

docs/index.rst

@@ -24,6 +24,7 @@ pytest-qt
     virtual_methods
     modeltester
     app_exit
+    note_pyqt4v2
     reference
     changelog
 

docs/intro.rst

@@ -40,19 +40,21 @@ this order:
 
 To force a particular API, set the configuration variable ``qt_api`` in your ``pytest.ini`` file to
 ``pyqt5``, ``pyside``, ``pyqt4`` or ``pyqt4v2``. ``pyqt4v2`` sets the ``PyQt4``
-API to `version 2 <version2>`_.
+API to `version 2`_.
 
 .. code-block:: ini
 
     [pytest]
     qt_api=pyqt5
 
+Alternatively, you can set the ``PYTEST_QT_API`` environment variable to the
+same values described above (the environment variable wins over the
+configuration if both are set).
 
-Alternatively, you can set the ``PYTEST_QT_API`` environment
-variable to the same values described above (the environment variable wins over the configuration
-if both are set).
+From ``pytest-qt`` version 2 the behaviour of ``pyqt4v2`` has changed, as
+explained in :doc:`note_pyqt4v2`.
 
-.. _version2: http://pyqt.sourceforge.net/Docs/PyQt4/incompatible_apis.html
+.. _version 2: http://pyqt.sourceforge.net/Docs/PyQt4/incompatible_apis.html
 
 Installation
 ------------
@@ -77,9 +79,13 @@ activate a new fresh environment and execute::
 
     git clone https://github.com/pytest-dev/pytest-qt.git
     cd pytest-qt
-    python setup.py develop
+    pip install -e .  # or python setup.py develop
     pip install pyside # or pyqt4/pyqt5
 
+If you also intend to build the documentation locally, you can make sure to have
+all the needed dependences executing::
+
+    pip install -e .[doc]
 
 .. _virtualenv: https://virtualenv.readthedocs.io/
 

docs/note_pyqt4v2.rst

@@ -0,0 +1,25 @@
+A note about ``pyqt4v2``
+------------------------
+
+Starting with ``pytest-qt`` version 2.0, ``PyQt`` or ``PySide`` are lazily
+loaded when first needed instead of at pytest startup. This usually means
+``pytest-qt`` will import ``PyQt`` or ``PySide`` when the tests actually start
+running, well after ``conftest.py`` files and other plugins have been imported.
+This can lead to some unexpected behaviour if ``pyqt4v2`` is set.
+
+If the ``conftest.py`` files, either directly or indirectly, set the API version
+to 2 and import ``PyQt4``, one of the following cases can happen:
+
+* if all the available types are set to version 2, then using ``pyqt4`` or
+  ``pyqt4v2`` is equivalent
+* if only some of the types set to version 2, using ``pyqt4v2`` will make ``pytest``
+  to fail with an error similar to::
+
+    INTERNALERROR> sip.setapi("QDate", 2)
+    INTERNALERROR> ValueError: API 'QDate' has already been set to version 1
+
+  If this is the case, use ``pyqt4``.
+
+If the API is set in the test functions or in the code imported by them, then
+the new behaviour is indistinguishable from the old one and ``pyqt4v2`` must be
+used to avoid errors if version 2 is used.

setup.py

@@ -37,6 +37,7 @@ def run_tests(self):
         'pytest11': ['pytest-qt = pytestqt.plugin'],
     },
     install_requires=['pytest>=2.7.0'],
+    extras_require={'doc': ['sphinx', 'sphinx_rtd_theme']},
 
     # metadata for upload to PyPI
     author="Bruno Oliveira",