From dbb4918c27bcee0267df15a452ff3c391363eb64 Mon Sep 17 00:00:00 2001 From: Corran Webster Date: Mon, 22 May 2023 13:50:47 +0100 Subject: [PATCH] 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 --- .../workflows/test-build-documentation.yml | 30 +++++++++++ CHANGES.txt | 52 +++++++++++++++++++ README.rst | 2 +- docs/source/conf.py | 1 - docs/source/traitsui_user_manual/intro.rst | 37 +++++++++++-- pyproject.toml | 2 +- 6 files changed, 118 insertions(+), 6 deletions(-) create mode 100644 .github/workflows/test-build-documentation.yml diff --git a/.github/workflows/test-build-documentation.yml b/.github/workflows/test-build-documentation.yml new file mode 100644 index 000000000..c86af4dab --- /dev/null +++ b/.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 diff --git a/CHANGES.txt b/CHANGES.txt index 73d362c6a..39bbb1aec 100644 --- a/CHANGES.txt +++ b/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 ------------- diff --git a/README.rst b/README.rst index 9072680c4..89def0940 100644 --- a/README.rst +++ b/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 `__, -``pip`` or other . +``pip`` or other package managers. .. end_of_long_description diff --git a/docs/source/conf.py b/docs/source/conf.py index e63795200..677264a93 100644 --- a/docs/source/conf.py +++ b/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 = { diff --git a/docs/source/traitsui_user_manual/intro.rst b/docs/source/traitsui_user_manual/intro.rst index 4da6f4111..ea3a1a7d5 100644 --- a/docs/source/traitsui_user_manual/intro.rst +++ b/docs/source/traitsui_user_manual/intro.rst @@ -119,9 +119,9 @@ are: .. index:: wxPython toolkit, Qt toolkit, null toolkit -* 'qt4' or 'qt': `PyQt `_ or - `Qt for Python/PySide2 `_, which provides Python - bindings for the `Qt `_ framework version 4 or 5. +* 'qt' or 'qt4': `PyQt5 `_, + `PySide2 or PySide6 `_, which provides Python + bindings for the `Qt `_ framework version 5 or 6. * 'wx': `wxPython `_, which provides Python bindings for the `wxWidgets `_ 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 diff --git a/pyproject.toml b/pyproject.toml index 85738bfaa..d4597031a 100644 --- a/pyproject.toml +++ b/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']