Skip to content

Commit e8f8c74

Browse files
FriedemannKleintFriedemannKleint
committed
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 <[email protected]>
1 parent 0f17567 commit e8f8c74

File tree

2 files changed

+109
-83
lines changed

2 files changed

+109
-83
lines changed

‎sources/pyside6/PySide6/QtCore/typesystem_core_common.xml

Lines changed: 14 additions & 83 deletions
Original file line numberDiff line numberDiff line change
@@ -86,19 +86,14 @@
8686
<add-function signature="Q_ARG(PyObject *@type@, PyObject *@value@)"
8787
return-type="QtCoreHelper::QGenericArgumentHolder">
8888
<inject-code file="../glue/qtcore.cpp" snippet="q_arg"/>
89-
<inject-documentation format="target" mode="append">
90-
This function takes a type (or a type string) and a value of that type
91-
and returns an internal object that can be passed to
92-
QMetaObject.invokeMethod(). See also Q_RETURN_ARG().
93-
</inject-documentation>
89+
<inject-documentation format="target" mode="append"
90+
file="../doc/qtcore.rst" snippet="q_arg"/>
9491
</add-function>
9592
<add-function signature="Q_RETURN_ARG(PyObject *@type@)"
9693
return-type="QtCoreHelper::QGenericReturnArgumentHolder">
9794
<inject-code file="../glue/qtcore.cpp" snippet="q_return_arg"/>
98-
<inject-documentation format="target" mode="append">
99-
This macro takes a type (or a type string) a value of which is then
100-
returned by QMetaObject::invokeMethod(). See also Q_ARG().
101-
</inject-documentation>
95+
<inject-documentation format="target" mode="append"
96+
file="../doc/qtcore.rst" snippet="q_return_arg"/>
10297
</add-function>
10398

10499
<!-- TODO: We do not support void* or const void* as arg -->
@@ -1382,25 +1377,8 @@
13821377
<add-function signature="system()" return-type="QLocale" static="yes">
13831378
<inject-code class="target" position="beginning" file="../glue/qtcore.cpp"
13841379
snippet="qlocale_system"/>
1385-
<inject-documentation mode="append" format="target">
1386-
Returns a QLocale object initialized to the system locale.
1387-
1388-
The system locale may use system-specific sources for locale data, where available,
1389-
otherwise falling back on QLocale's built-in database entry for the language, script and
1390-
territory the system reports.
1391-
1392-
For example, on Windows, this locale will use the decimal/grouping characters and
1393-
date/time formats specified in the system configuration panel.
1394-
1395-
.. note:: Qt for Python on macOS will not reflect the user's region and language
1396-
preferences though QLocale::system(), but will instead reflect the environment
1397-
variables POSIX uses to specify locale, similar to Python's locale module. If the
1398-
system locale cannot be determined, which can be due to none of the variables 'LC_ALL',
1399-
'LC_CTYPE', 'LANG' or 'LANGUAGE' being set by your environment, then the default POSIX
1400-
locale or 'C' locale is returned.
1401-
1402-
See also c().
1403-
</inject-documentation>
1380+
<inject-documentation mode="append" format="target"
1381+
file="../doc/qtcore.rst" snippet="qlocale-system"/>
14041382
</add-function>
14051383
<modify-function signature="toTime(QString,QLocale::FormatType)const">
14061384
<modify-argument index="2">
@@ -1676,18 +1654,8 @@
16761654
</modify-function>
16771655
<add-function signature="createIndex(int@row@,int@column@,PyObject*@ptr@)const" return-type="QModelIndex">
16781656
<inject-code class="target" position="beginning" file="../glue/qtcore.cpp" snippet="qabstractitemmodel-createindex"/>
1679-
<inject-documentation mode="append" format="target">
1680-
Creates a model index for the given row and column with the internal pointer ptr.
1681-
When using a QSortFilterProxyModel, its indexes have their own internal pointer.
1682-
It is not advisable to access this internal pointer outside of the model.
1683-
Use the data() function instead.
1684-
This function provides a consistent interface that model subclasses must use to create model indexes.
1685-
1686-
.. warning:: Because of some Qt/Python itegration rules, the ptr argument do not get the reference
1687-
incremented during the QModelIndex life time. So it is necessary to keep the object used
1688-
on ptr argument alive during the whole process.
1689-
Do not destroy the object if you are not sure about that.
1690-
</inject-documentation>
1657+
<inject-documentation mode="append" format="target"
1658+
file="../doc/qtcore.rst" snippet="qabstractitemmodel-createindex"/>
16911659
</add-function>
16921660
<inject-code class="target" position="end" file="../glue/qtcore.cpp" snippet="qabstractitemmodel"/>
16931661
<modify-function signature="mimeData(QList&lt;QModelIndex&gt;)const">
@@ -1864,19 +1832,8 @@
18641832

18651833
<add-function signature="findChild(PyTypeObject*@type@,const QString&amp;@name@={},Qt::FindChildOptions@options@=Qt::FindChildrenRecursively)"
18661834
return-type="PyObject*">
1867-
<inject-documentation format="target" mode="append">
1868-
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:
1869-
1870-
::
1871-
1872-
...
1873-
parent = QWidget()
1874-
...
1875-
# The first argument must be the child type
1876-
child1 = parent.findChild(QPushButton, "child_button")
1877-
child2 = parent.findChild(QWidget, "child_widget")
1878-
1879-
</inject-documentation>
1835+
<inject-documentation format="target" mode="append"
1836+
file="../doc/qtcore.rst" snippet="qobject-findChild"/>
18801837
<inject-code class="target" position="beginning" file="../glue/qtcore.cpp" snippet="qobject-findchild-2"/>
18811838
<modify-argument index="return" pyi-type="Optional[PlaceHolderType]">
18821839
<parent index="this" action="add"/>
@@ -2696,15 +2653,8 @@
26962653
</extra-includes>
26972654
<add-function signature="QCoreApplication(QStringList@args@)">
26982655
<inject-code file="../glue/qtcore.cpp" snippet="qcoreapplication-1"/>
2699-
<inject-documentation format="target" mode="append">
2700-
Constructs a Qt kernel application. Kernel applications are applications
2701-
without a graphical user interface. These type of applications are used
2702-
at the console or as server processes.
2703-
2704-
The *args* argument is processed by the application, and made available
2705-
in a more convenient form by the :meth:`~PySide6.QtCore.QCoreApplication.arguments()`
2706-
method.
2707-
</inject-documentation>
2656+
<inject-documentation format="target" mode="append"
2657+
file="../doc/qtcore.rst" snippet="qcoreapplication-init"/>
27082658
</add-function>
27092659
<add-function signature="QCoreApplication()">
27102660
<inject-code file="../glue/qtcore.cpp" snippet="qcoreapplication-2"/>
@@ -2792,27 +2742,8 @@
27922742
<modify-function signature="value(QAnyStringView,const QVariant&amp;)const" remove="all"/>
27932743
<add-function signature="value(const QString&amp;, const QVariant&amp; @defaultValue@ = {}, PyObject* @type@ = nullptr)" return-type="PyObject*">
27942744
<inject-code class="target" position="beginning" file="../glue/qtcore.cpp" snippet="qsettings-value"/>
2795-
<inject-documentation mode="append" format="target">
2796-
Custom overload that adds an optional named parameter to the function ``value()``
2797-
to automatically cast the type that is being returned by the function.
2798-
2799-
An example of this situation could be an ini file that contains
2800-
the value of a one-element list::
2801-
2802-
settings.setValue('var', ['a'])
2803-
2804-
The the ini file will be::
2805-
2806-
[General]
2807-
var=a # we cannot know that this is a list!
2808-
2809-
Once we read it, we could specify if we want
2810-
the default behavior, a str, or to cast the output
2811-
to a list.
2812-
2813-
settings.value('var') # Will get "a"
2814-
settings.value('var', type=list) # Will get ["a"]
2815-
</inject-documentation>
2745+
<inject-documentation mode="append" format="target"
2746+
file="../doc/qtcore.rst" snippet="qsettings-value"/>
28162747
</add-function>
28172748
</object-type>
28182749
<object-type name="QEvent" polymorphic-id-expression="%1-&gt;type() == QEvent::None"

‎sources/pyside6/PySide6/doc/qtcore.rst

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
// @snippet q_arg
2+
This function takes a type (or a type string) and a value of that type
3+
and returns an internal object that can be passed to
4+
:meth:`QMetaObject.invokeMethod`. See also Q_RETURN_ARG().
5+
// @snippet q_arg
6+
7+
// @snippet q_return_arg
8+
This macro takes a type (or a type string) a value of which is then
9+
returned by :meth:`QMetaObject.invokeMethod`. See also Q_ARG().
10+
// @snippet q_return_arg
11+
12+
// @snippet qlocale-system
13+
Returns a QLocale object initialized to the system locale.
14+
15+
The system locale may use system-specific sources for locale data, where
16+
available, otherwise falling back on QLocale's built-in database entry for the
17+
language, script and territory the system reports.
18+
19+
For example, on Windows, this locale will use the decimal/grouping characters and
20+
date/time formats specified in the system configuration panel.
21+
22+
.. note:: Qt for Python on macOS will not reflect the user's region and language
23+
preferences though QLocale::system(), but will instead reflect the
24+
environment variables POSIX uses to specify locale, similar to Python's
25+
locale module. If the system locale cannot be determined, which can be
26+
due to none of the variables 'LC_ALL', 'LC_CTYPE', 'LANG' or 'LANGUAGE'
27+
being set by your environment, then the default POSIX locale or
28+
'C' locale is returned.
29+
30+
See also c().
31+
// @snippet qlocale-system
32+
33+
// @snippet qabstractitemmodel-createindex
34+
Creates a model index for the given row and column with the internal pointer
35+
ptr. When using a :class:`QSortFilterProxyModel`, its indexes have their own
36+
internal pointer. It is not advisable to access this internal pointer outside
37+
of the model. Use the ``data()`` function instead.
38+
39+
This function provides a consistent interface that model subclasses must use to
40+
create model indexes.
41+
42+
.. warning:: Because of some Qt/Python integration rules, the ``ptr`` argument does
43+
not get the reference incremented during the QModelIndex life time.
44+
So it is necessary to keep the object used on ``ptr`` argument alive
45+
during the whole process. Do not destroy the object if you are not
46+
sure about that.
47+
// @snippet qabstractitemmodel-createindex
48+
49+
// @snippet qobject-findChild
50+
To find the child of a certain :class:`QObject`, the first argument of this
51+
function should be the child's type, and the second the name of the child:
52+
53+
::
54+
55+
...
56+
parent = QWidget()
57+
...
58+
# The first argument must be the child type
59+
child1 = parent.findChild(QPushButton, "child_button")
60+
child2 = parent.findChild(QWidget, "child_widget")
61+
62+
// @snippet qobject-findChild
63+
64+
// @snippet qcoreapplication-init
65+
Constructs a Qt kernel application. Kernel applications are applications
66+
without a graphical user interface. These type of applications are used
67+
at the console or as server processes.
68+
69+
The *args* argument is processed by the application, and made available
70+
in a more convenient form by the :meth:`~PySide6.QtCore.QCoreApplication.arguments()`
71+
method.
72+
// @snippet qcoreapplication-init
73+
74+
// @snippet qsettings-value
75+
Custom overload that adds an optional named parameter to the function ``value()``
76+
to automatically cast the type that is being returned by the function.
77+
78+
An example of this situation could be an ini file that contains
79+
the value of a one-element list::
80+
81+
settings.setValue('var', ['a'])
82+
83+
The the ini file will be::
84+
85+
[General]
86+
var=a # we cannot know that this is a list!
87+
88+
Once we read it, we could specify if we want
89+
the default behavior, a str, or to cast the output
90+
to a list.
91+
92+
settings.value('var') # Will get "a"
93+
settings.value('var', type=list) # Will get ["a"]
94+
95+
// @snippet qsettings-value

0 commit comments

Comments
 (0)