Update documentation in preparation for 8.0 release (#2021)

This PR:

- Updates the changelog for 8.0
- describe changes to toolkit behaviour
- adds tests for documentation on each PR

.github/workflows/test-build-documentation.yml

@@ -0,0 +1,30 @@
+name: Test documentation build
+
+on:
+  pull_request
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python 3.11
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.11'
+    - name: Install dependencies and local packages
+      run: python -m pip install .[docs]
+    - name: Autogenerate API documentation
+      run: |
+        sphinx-apidoc -e -M --no-toc -o docs/source/api traitsui traitsui/qt4/* traitsui/qt/* traitsui/wx/* */tests
+    - name: Build HTML documentation with Sphinx
+      run: |
+        sphinx-build -b html -d build/doctrees source build/html
+      working-directory: docs
+    - name: Archive HTML documentation
+      uses: actions/upload-artifact@v3
+      with:
+        name: docs-html
+        path: docs/build/html
+        retention-days: 5

CHANGES.txt

@@ -1,6 +1,58 @@
 Traits UI Changelog
 ===================
 
+Release 8.0.0
+-------------
+
+This is a major release that provides support for PySide 6.4 and 6.5 as well
+as Python 3.11.  It includes a number of backwards-incompatible changes
+following the example of Pyface 8.0.0, most notable is moving the
+`traitsui.qt4.*` modules to `traitsui.qt.*`.  As with Pyface 8.0 we include
+a backwards-compatibility mode which allows importing from the 'qt4' namespace
+via:
+
+- setting the ETS toolkit to `"qt4"`
+- setting the ETS_QT4_IMPORTS environment variable
+- manually adding appropriate finders to sys.meta_path
+
+This release also removes a number of features deprecated since TraitsUI 7.0.
+
+Thanks To
+---------
+
+* David Baddeley
+* Mark Dickinson
+* Dominik Gresch
+* hopeful0
+* Chengyu Liu
+* Orion Poplawski
+* Corran Webster
+
+Features
+--------
+
+* Be strict about 'handler.init()' return values (#2008)
+* Move 'traitsui.qt4.*' to 'traitsui.qt.*' (#2004)
+* Remove deprecated 'format' trait (#2002)
+* Deprecate imports from traitsui.editors (use traitsui.editors.api) (#2000)
+* Remove backwards-compatibility mode in undo/redo code (#1999)
+* Support for Python 3.11 and PySide 6.4+ (#1994)
+
+Fixes
+-----
+
+* Fix uses of None in date range editor (#2019)
+* Add comments for Wx-only examples (#2011, #2020)
+* Replace uses of "fast_ui" dispatch with "ui" dispatch (#2009)
+* Fix FileDialog selection actions (#2003)
+* Fix regression in Wx version of FileEditor (#1993)
+* Fix missing attribute of InstanceFactoryChocie (#1989)
+
+Test suite
+----------
+
+* Replace some relative imports in tests (#1985)
+
 Release 7.4.3
 -------------
 

README.rst

@@ -77,7 +77,7 @@ NumPy and Pandas for some editors.
 
 TraitsUI along with all dependencies can be installed in a straightforward way
 using the `Enthought Deployment Manager <http://docs.enthought.com/edm/>`__,
-``pip`` or other .
+``pip`` or other package managers.
 
 .. end_of_long_description
 

docs/source/conf.py

@@ -228,7 +228,6 @@
 # latex_use_modindex = True
 
 # Autodoc options
-autodo_mock_imports = ["wx", "PySide", "PyQt", "PyQt5"]
 
 # Intersphinx configuration
 intersphinx_mapping = {

docs/source/traitsui_user_manual/intro.rst

@@ -119,9 +119,9 @@ are:
 
 .. index:: wxPython toolkit, Qt toolkit, null toolkit
 
-* 'qt4' or 'qt': `PyQt <http://riverbankcomputing.co.uk/pyqt/>`_ or
-  `Qt for Python/PySide2 <https://doc.qt.io/qtforpython/>`_, which provides Python
-  bindings for the `Qt <https://www.qt.io/>`_ framework version 4 or 5.
+* 'qt' or 'qt4': `PyQt5 <http://riverbankcomputing.co.uk/pyqt/>`_,
+  `PySide2 or PySide6 <https://doc.qt.io/qtforpython/>`_, which provides Python
+  bindings for the `Qt <https://www.qt.io/>`_ framework version 5 or 6.
 * 'wx': `wxPython <http://www.wxpython.org>`_, which provides Python bindings
   for the `wxWidgets <http://wxwidgets.org>`_ toolkit.
 * 'null': A do-nothing toolkit, for situations where neither of the other
@@ -144,6 +144,37 @@ order of precedence:
 
 #. The user can define a value for the ETS_TOOLKIT environment variable.
 
+Toolkit selection is largely carried out in Pyface rather than TraitsUI, where
+further details can be found.
+
+The "qt4" Toolkit
+`````````````````
+
+The "qt4" toolkit is the same as the "qt" toolkit in almost all respects:
+in older versions of TraitsUI it was the standard name for all the Qt-based
+toolkits whether or not they were actually using Qt4.
+
+However it does trigger some backwards-compatibility code that may be useful
+for legacy applications. In particular it installs import hooks that makes the
+``traitsui.qt4.*`` package namespace an alias for ``traitsui.qt.*`` modules.
+
+This backwards-compatibility code can also be invoked by setting the
+``ETS_QT4_IMPORTS`` environment variable to any non-empty value, or adding
+an instance of the :py:class:`pyface.ui.ShadowedModuleFinder` module finder
+to :py:attr:`sys.meta_path` list.
+
+..  warning::
+
+    Library code which imports from ``traitsui.qt4.*`` should not use this
+    compatibility code.  Instead it should be updated to import from
+    ``traitsui.qt.*`` as soon as practical.  Backwards-compatibility can be
+    achieved fairly easily by using :py:attr:`traitsui.toolkit.toolkit` to
+    access objects rather than direct imports.
+
+This backwards-compatibility code will be removed in TraitsUI 9, and
+applications which rely on the particulars of the implementation are encouraged
+to migrate to the newer import locations as soon as practical.
+
 .. _structure-of-this-guide:
 
 Structure of this Manual

pyproject.toml

@@ -30,7 +30,7 @@ null = 'traitsui.null:toolkit'
 demo = 'traitsui.extras._demo_info:info'
 
 [project.optional-dependencies]
-docs = ['enthought-sphinx-theme', 'sphinx', 'sphinx-copybutton']
+docs = ['enthought-sphinx-theme', 'sphinx', 'sphinx-copybutton', 'configobj']
 editors = ['numpy', 'pandas']
 examples = ['apptools', 'h5py', 'numpy', 'pandas', 'pillow', 'tables']
 pyqt5 = ['pyqt5', 'pygments']