Add a new module

New modules can be added for many reasons, the most important one is when Qt enables or includes a new one for a new release.

Adding the bindings, and documentation are the essentials to include new modules, but adding tests and examples is ideal.

Add bindings

  • Find the correct name (look at the include path of Qt).

  • Add the module to the coin/dependencies.yaml file.

  • Add it to sources/pyside6/cmake/PySideHelpers.cmake.

  • Add it to build_scripts/wheel_files.py (plugins, translations).

  • Copy an existing module to sources/pyside6/PySide6/<name>.

  • Adapt the typesystem.xml and CMakeList.txt (using for example Qt Creator’s case-preserving replace function).

  • Make sure the dependencies are correct.

  • Find the exported public classes, add them to the typesystem.xml file, checking whether they are value-type or object-type. Add their enums and flags.

  • Add the wrapper files to CMakeList.txt.

  • Create a test dir under sources/pyside6/tests with an empty CMakeList.txt.

  • Try to build with the module added to the --module-subset option of setup.py.

  • Watch out for shiboken warnings in the log.

  • Be aware that ninja mixes stdout and stderr, so, the first warning is typically hidden behind a progress message.

  • A convenient way of doing this is using qt-creator/scripts/shiboken2tasks.py from the *Qt Creator* repository converting them to a .tasks file which can be loaded into Qt Creator’s issue pane.

  • Link errors may manifest when generate_pyi imports the module trying to create signatures. They indicate a missing source file entry or a bug in the module itself.

Note

For the build to succeed, the module must follow the Qt convention of using #include <QtModule/header.h> since module include paths are not passed in PySide.

Distribution

  • Determine to which wheel the module belongs according to Qt Modules.

  • Add the module to build_scripts/wheel_files.py for use by create_wheels.py.

  • Add the module to one of the README.pyside6_*.md files.

Add documentation

  • Add entry to sources/pyside6/doc/modules.rst.

  • Add a .qdocconf.in file in sources/pyside6/doc/qtmodules.

  • Add module description .rst file in sources/pyside6/doc/extras:

    • Run a full documentation build

    • Copy the auto-generated file <build>/pyside6/doc/base/<Module>/index.rst to sources/pyside6/doc/extras/<Module>/<Module>.rst

    • Remove TOC, qmake/CMake instructions and class lists (cf existing files)

    • Check the references, preferably link to converted documents in PySide or add documents there (see Maintaining additionaldocs.lst).