diff options
| author | Friedemann Kleint <Friedemann.Kleint@qt.io> | 2024-10-25 10:00:08 +0200 |
|---|---|---|
| committer | Friedemann Kleint <Friedemann.Kleint@qt.io> | 2024-10-25 10:48:58 +0200 |
| commit | e8f8c749344142c390c661d6d01c34168c1c3ec4 (patch) | |
| tree | 359fd3866415116657d19b66f99b35edf670d0ff /sources/pyside6/PySide6 | |
| parent | 0f1756769b66152c561233bb2de1ce3e21a8321f (diff) | |
Documentation: Fix build with module subset failing due to missing doc directory
Extract longer QtCore documentation snippets to a separate file such
that a minimum build also has doc snippets. This also makes maintenance
easier.
Pick-to: 6.8
Change-Id: I9fb0c93f52d3560e2e07cff076ae516ba96c90a4
Reviewed-by: Cristian Maureira-Fredes <cristian.maureira-fredes@qt.io>
Diffstat (limited to 'sources/pyside6/PySide6')
| -rw-r--r-- | sources/pyside6/PySide6/QtCore/typesystem_core_common.xml | 97 | ||||
| -rw-r--r-- | sources/pyside6/PySide6/doc/qtcore.rst | 95 |
2 files changed, 109 insertions, 83 deletions
diff --git a/sources/pyside6/PySide6/QtCore/typesystem_core_common.xml b/sources/pyside6/PySide6/QtCore/typesystem_core_common.xml index e9bbc6249..c7a3efe77 100644 --- a/sources/pyside6/PySide6/QtCore/typesystem_core_common.xml +++ b/sources/pyside6/PySide6/QtCore/typesystem_core_common.xml @@ -86,19 +86,14 @@ <add-function signature="Q_ARG(PyObject *@type@, PyObject *@value@)" return-type="QtCoreHelper::QGenericArgumentHolder"> <inject-code file="../glue/qtcore.cpp" snippet="q_arg"/> - <inject-documentation format="target" mode="append"> - This function takes a type (or a type string) and a value of that type - and returns an internal object that can be passed to - QMetaObject.invokeMethod(). See also Q_RETURN_ARG(). - </inject-documentation> + <inject-documentation format="target" mode="append" + file="../doc/qtcore.rst" snippet="q_arg"/> </add-function> <add-function signature="Q_RETURN_ARG(PyObject *@type@)" return-type="QtCoreHelper::QGenericReturnArgumentHolder"> <inject-code file="../glue/qtcore.cpp" snippet="q_return_arg"/> - <inject-documentation format="target" mode="append"> - This macro takes a type (or a type string) a value of which is then - returned by QMetaObject::invokeMethod(). See also Q_ARG(). - </inject-documentation> + <inject-documentation format="target" mode="append" + file="../doc/qtcore.rst" snippet="q_return_arg"/> </add-function> <!-- TODO: We do not support void* or const void* as arg --> @@ -1382,25 +1377,8 @@ <add-function signature="system()" return-type="QLocale" static="yes"> <inject-code class="target" position="beginning" file="../glue/qtcore.cpp" snippet="qlocale_system"/> - <inject-documentation mode="append" format="target"> - Returns a QLocale object initialized to the system locale. - - The system locale may use system-specific sources for locale data, where available, - otherwise falling back on QLocale's built-in database entry for the language, script and - territory the system reports. - - For example, on Windows, this locale will use the decimal/grouping characters and - date/time formats specified in the system configuration panel. - - .. note:: Qt for Python on macOS will not reflect the user's region and language - preferences though QLocale::system(), but will instead reflect the environment - variables POSIX uses to specify locale, similar to Python's locale module. If the - system locale cannot be determined, which can be due to none of the variables 'LC_ALL', - 'LC_CTYPE', 'LANG' or 'LANGUAGE' being set by your environment, then the default POSIX - locale or 'C' locale is returned. - - See also c(). - </inject-documentation> + <inject-documentation mode="append" format="target" + file="../doc/qtcore.rst" snippet="qlocale-system"/> </add-function> <modify-function signature="toTime(QString,QLocale::FormatType)const"> <modify-argument index="2"> @@ -1676,18 +1654,8 @@ </modify-function> <add-function signature="createIndex(int@row@,int@column@,PyObject*@ptr@)const" return-type="QModelIndex"> <inject-code class="target" position="beginning" file="../glue/qtcore.cpp" snippet="qabstractitemmodel-createindex"/> - <inject-documentation mode="append" format="target"> - Creates a model index for the given row and column with the internal pointer ptr. - When using a QSortFilterProxyModel, its indexes have their own internal pointer. - It is not advisable to access this internal pointer outside of the model. - Use the data() function instead. - This function provides a consistent interface that model subclasses must use to create model indexes. - - .. warning:: Because of some Qt/Python itegration rules, the ptr argument do not get the reference - incremented during the QModelIndex life time. So it is necessary to keep the object used - on ptr argument alive during the whole process. - Do not destroy the object if you are not sure about that. - </inject-documentation> + <inject-documentation mode="append" format="target" + file="../doc/qtcore.rst" snippet="qabstractitemmodel-createindex"/> </add-function> <inject-code class="target" position="end" file="../glue/qtcore.cpp" snippet="qabstractitemmodel"/> <modify-function signature="mimeData(QList<QModelIndex>)const"> @@ -1864,19 +1832,8 @@ <add-function signature="findChild(PyTypeObject*@type@,const QString&@name@={},Qt::FindChildOptions@options@=Qt::FindChildrenRecursively)" return-type="PyObject*"> - <inject-documentation format="target" mode="append"> - To find the child of a certain QObject, the first argument of this function should be the child's type, and the second the name of the child: - - :: - - ... - parent = QWidget() - ... - # The first argument must be the child type - child1 = parent.findChild(QPushButton, "child_button") - child2 = parent.findChild(QWidget, "child_widget") - - </inject-documentation> + <inject-documentation format="target" mode="append" + file="../doc/qtcore.rst" snippet="qobject-findChild"/> <inject-code class="target" position="beginning" file="../glue/qtcore.cpp" snippet="qobject-findchild-2"/> <modify-argument index="return" pyi-type="Optional[PlaceHolderType]"> <parent index="this" action="add"/> @@ -2696,15 +2653,8 @@ </extra-includes> <add-function signature="QCoreApplication(QStringList@args@)"> <inject-code file="../glue/qtcore.cpp" snippet="qcoreapplication-1"/> - <inject-documentation format="target" mode="append"> - Constructs a Qt kernel application. Kernel applications are applications - without a graphical user interface. These type of applications are used - at the console or as server processes. - - The *args* argument is processed by the application, and made available - in a more convenient form by the :meth:`~PySide6.QtCore.QCoreApplication.arguments()` - method. - </inject-documentation> + <inject-documentation format="target" mode="append" + file="../doc/qtcore.rst" snippet="qcoreapplication-init"/> </add-function> <add-function signature="QCoreApplication()"> <inject-code file="../glue/qtcore.cpp" snippet="qcoreapplication-2"/> @@ -2792,27 +2742,8 @@ <modify-function signature="value(QAnyStringView,const QVariant&)const" remove="all"/> <add-function signature="value(const QString&, const QVariant& @defaultValue@ = {}, PyObject* @type@ = nullptr)" return-type="PyObject*"> <inject-code class="target" position="beginning" file="../glue/qtcore.cpp" snippet="qsettings-value"/> - <inject-documentation mode="append" format="target"> - Custom overload that adds an optional named parameter to the function ``value()`` - to automatically cast the type that is being returned by the function. - - An example of this situation could be an ini file that contains - the value of a one-element list:: - - settings.setValue('var', ['a']) - - The the ini file will be:: - - [General] - var=a # we cannot know that this is a list! - - Once we read it, we could specify if we want - the default behavior, a str, or to cast the output - to a list. - - settings.value('var') # Will get "a" - settings.value('var', type=list) # Will get ["a"] - </inject-documentation> + <inject-documentation mode="append" format="target" + file="../doc/qtcore.rst" snippet="qsettings-value"/> </add-function> </object-type> <object-type name="QEvent" polymorphic-id-expression="%1->type() == QEvent::None" diff --git a/sources/pyside6/PySide6/doc/qtcore.rst b/sources/pyside6/PySide6/doc/qtcore.rst new file mode 100644 index 000000000..35ba0d1cd --- /dev/null +++ b/sources/pyside6/PySide6/doc/qtcore.rst @@ -0,0 +1,95 @@ +// @snippet q_arg +This function takes a type (or a type string) and a value of that type +and returns an internal object that can be passed to +:meth:`QMetaObject.invokeMethod`. See also Q_RETURN_ARG(). +// @snippet q_arg + +// @snippet q_return_arg +This macro takes a type (or a type string) a value of which is then +returned by :meth:`QMetaObject.invokeMethod`. See also Q_ARG(). +// @snippet q_return_arg + +// @snippet qlocale-system +Returns a QLocale object initialized to the system locale. + +The system locale may use system-specific sources for locale data, where +available, otherwise falling back on QLocale's built-in database entry for the +language, script and territory the system reports. + +For example, on Windows, this locale will use the decimal/grouping characters and +date/time formats specified in the system configuration panel. + +.. note:: Qt for Python on macOS will not reflect the user's region and language + preferences though QLocale::system(), but will instead reflect the + environment variables POSIX uses to specify locale, similar to Python's + locale module. If the system locale cannot be determined, which can be + due to none of the variables 'LC_ALL', 'LC_CTYPE', 'LANG' or 'LANGUAGE' + being set by your environment, then the default POSIX locale or + 'C' locale is returned. + +See also c(). +// @snippet qlocale-system + +// @snippet qabstractitemmodel-createindex +Creates a model index for the given row and column with the internal pointer +ptr. When using a :class:`QSortFilterProxyModel`, its indexes have their own +internal pointer. It is not advisable to access this internal pointer outside +of the model. Use the ``data()`` function instead. + +This function provides a consistent interface that model subclasses must use to +create model indexes. + +.. warning:: Because of some Qt/Python integration rules, the ``ptr`` argument does + not get the reference incremented during the QModelIndex life time. + So it is necessary to keep the object used on ``ptr`` argument alive + during the whole process. Do not destroy the object if you are not + sure about that. +// @snippet qabstractitemmodel-createindex + +// @snippet qobject-findChild +To find the child of a certain :class:`QObject`, the first argument of this +function should be the child's type, and the second the name of the child: + +:: + + ... + parent = QWidget() + ... + # The first argument must be the child type + child1 = parent.findChild(QPushButton, "child_button") + child2 = parent.findChild(QWidget, "child_widget") + +// @snippet qobject-findChild + +// @snippet qcoreapplication-init +Constructs a Qt kernel application. Kernel applications are applications +without a graphical user interface. These type of applications are used +at the console or as server processes. + +The *args* argument is processed by the application, and made available +in a more convenient form by the :meth:`~PySide6.QtCore.QCoreApplication.arguments()` +method. +// @snippet qcoreapplication-init + +// @snippet qsettings-value +Custom overload that adds an optional named parameter to the function ``value()`` +to automatically cast the type that is being returned by the function. + +An example of this situation could be an ini file that contains +the value of a one-element list:: + + settings.setValue('var', ['a']) + +The the ini file will be:: + + [General] + var=a # we cannot know that this is a list! + +Once we read it, we could specify if we want +the default behavior, a str, or to cast the output +to a list. + + settings.value('var') # Will get "a" + settings.value('var', type=list) # Will get ["a"] + +// @snippet qsettings-value |