There is a squish-tested-example.qdocinc file which contains squish testing
information for examples.
This patch includes this file into the app-exampls-template file as an optional
section. It should be added if the example was tested with squish.
The README was also updated to include this information.
Fixes: QTBUG-139284
Pick-to: 6.10
Change-Id: I69fde08cab19fb81897de2066e553a9d4a51d823
Reviewed-by: Jerome Pasion <jerome.pasion@qt.io>
A double-colon in a link target causes QDoc to treat it as a
qualified name of an API entity, causing the link resolution to
fail.
Drop the double-colons from the \title; fixes QDoc warnings such as
src/testlib/doc/qtestcase.qdoc: (qdoc) warning: Can't link to
'std::literals::chrono_literals Symbol Index'
Pick-to: 6.10 6.9 6.8
Change-Id: Ibf848e776a23e5528a8a98b7dddf943f0084efb2
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
This patch changes the 'relevant classes' section title to
'relevant modules and classes'. This makes it more inclusive and it can
be applicable to either modules or classes.
Fixes: QTBUG-139292
Pick-to: 6.10
Change-Id: I418edadd1b58d12ad6f7c82b2aed53bf53abdc6a
Reviewed-by: Jerome Pasion <jerome.pasion@qt.io>
Currently the app-examples-template.qdoc file contains a mandatory
'Platform Notes' section. This section lists the different platforms
that the example can be run on. Since all Qt application examples are
cross-platform, this information is not necessary.
This patch states that the 'Platform Notes' section is optional and
should be used if there are any plaform limitations or exceptions.
Fixes: QTBUG-139286
Pick-to: 6.10
Change-Id: Iad10b1cc5a5ca4880e92327d1ffd77b61988e72d
Reviewed-by: Andreas Eliasson <andreas.eliasson@qt.io>
Add squish-tested-example.qdocinc for global accessibility in all
submodules.
This precedes a patch removing the file from qdoc module.
Task-number: QTBUG-139338
Pick-to: 6.10
Change-Id: I278e8d723cda1c4d530120bfcbc7fb7916c533a4
Reviewed-by: Nicholas Bennett <nicholas.bennett@qt.io>
We are updating the structure of the application examples.
This patch creates a template and a README document that developers can use for
creating/updating application examples.
This template describes the content that should be included in an application
example.
Fixes: QTBUG-137901
Pick-to: 6.10
Change-Id: Ida3fd1ee4c0b9136a4eaa55209b75557e3ba8cb5
Reviewed-by: Jerome Pasion <jerome.pasion@qt.io>
This makes it easier for readers to find out what this is, in case
they don't know, yet.
Amends d4bb448cdd.
Pick-to: 6.10 6.9 6.8
Change-Id: If2130512c34f974a45af19099bc1dd13d006e186
Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>
Recent changes in QDoc's output for QML type reference pages included
rearranging the `extra synopsis` element, i.e, read-only, since, and
deprecation information for properties.
As a result, the existing CSS for the offline documentation caused some
elements to be rendered on top of each other when using the qlitehtml-
based backend in Qt Assistant and Qt Creator.
To fix the layout, set a fixed width for the table elements that
are used to display the properties, property groups, and methods.
This change brings the style of QML reference pages closer to that
of C++ reference, where signatures also have a fixed width.
Pick-to: 6.10 6.9 6.8
Fixes: QTBUG-136990
Change-Id: I72adbeaca46cd9dd99c54368257268dc8db6bfdc
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
Reviewed-by: David Boddie <david.boddie@qt.io>
Since 6.10, QDoc is capable of generating links to the declaration in
the source code for each documented C++ API entity in their `Detailed
description`.
Add the required configuration to enable this feature in online
documentation builds.
Change-Id: Iaafabc5aea50a6cd72549bb1c04007bb4de498ca
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
This reverts commit 5c0b08a20d.
After the original commit, DocBook support for tabbed
content was introduced (as format-specific macros). This
means that the original macros will also have to be HTML-format
specific, as macros cannot have both default and
format-specific variants defined.
In addition to reverting, add linefeeds to (end)tabcontent.HTML
macros to solve the same problem that the reverted commit did.
In passing, fix an issue with the tabcontent.DocBook macro; it
takes a single argument, therefore the placeholder for the
value must be \1.
Change-Id: I90ed6bc37d70c10754b3b810198ac44fcd189766
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
Reviewed-by: David Boddie <david.boddie@qt.io>
The existing implementation only works for online HTML and the
workaround generates nonsensical DocBook that not a single processor
could parse.
This implementation is not ideal, but gives enough information for
processors to do their job (i.e. the tab title and contents are uniquely
linked, the tabs in a group are related). Unaware processors still
render useful information to the user thanks to links.
The ideal presentation would use a container such as `formalgroup` for
the tabs, but there is no notion of tab in DocBook.
The missing part in this patch is allowing all uses of tabs with DocBook; they are still guarded by `\if defined(onlinedocs)`.
For instance, this change updates `porting-to-ios.xml` from:
```xml
<db:listitem…>
<db:para>If your application uses imports or plugins that depend on special Qt modules, these Qt modules should be added to your build configuration file. For example, if your application uses the Qt Multimedia import in QML, you should add the following to your .pro or CMakeLists.txt file: </db:para>
<db:section xml:id="using-cmake">
<db:title>Using CMake</db:title>
<db:programlisting language="cpp" role="bad">find_package(Qt6 REQUIRED COMPONENTS Multimedia)
target_link_libraries(my_project PRIVATE Qt6::Multimedia)
</db:programlisting>
</db:section>
<db:section xml:id="using-qmake">
<db:title>Using qmake</db:title>
<db:programlisting language="cpp" role="bad">QT += multimedia
</db:programlisting>
<db:para>In Qt for iOS, everything is compiled statically and placed into the application bundle. The applications are "sandboxed" inside their bundles and cannot make use of shared object files. Because of this, also the plugins used by the Qt modules need to be statically linked. To do this, define the required plugins using the <db:link xlink:href="qmake-variable-reference.xml#qtplugin">QTPLUGIN</db:link> variable.</db:para>
</db:section>
```
to:
```xml
<db:listitem…>
<db:para>If your application uses imports or plugins that depend on special Qt modules, these Qt modules should be added to your build configuration file. For example, if your application uses the Qt Multimedia import in QML, you should add the following to your .pro or CMakeLists.txt file: </db:para>
<db:bridgehead xml:id="tab-cmake" renderas="sect5" role="tabbed checked tab-group_build-ios-app" xlink:href="#tab-cmake_contents">CMake</db:bridgehead>
<db:bridgehead xml:id="tab-qmake" renderas="sect5" role="tabbed checked tab-group_build-ios-app" xlink:href="#tab-qmake_contents">qake</db:bridgehead>
<db:sidebar xml:id="tab-cmake_contents">
<db:programlisting language="cpp" role="bad">find_package(Qt6 REQUIRED COMPONENTS Multimedia)
target_link_libraries(my_project PRIVATE Qt6::Multimedia)
</db:programlisting>
</db:sidebar>
<db:sidebar xml:id="tab-qmake_contents">
<db:programlisting language="cpp" role="bad">QT += multimedia
</db:programlisting>
</db:sidebar>
```
Change-Id: I63f3e8d03a5f4ee52e7c67971d14d4497dd78cb8
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
This regex pattern instructs QDoc to not include the matching warning in
its warning count. The warning has changed to a report, however, which
won't count towards the warning count in any case, so the regexp isn't
needed anymore.
Task-number: QTBUG-131459
Task-number: QTBUG-134219
Pick-to: 6.9 6.8
Change-Id: Ic461c63b62bd25fb2d1f3b485c46db55e52e20cf
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
Updated the macros in qtbase to propagate changes to other doc
projects. A separate change has been raised to handle multiple supported
ndks in prior LTSs
Task-number: QTQAINFRA-6479
Change-Id: Ic052f1b6b80473cc33c7f2be23049969d3cec0ee
Reviewed-by: Assam Boudjelthia <assam.boudjelthia@qt.io>
The current style adds padding to non-pre elements, such as any p or div
elements. The final html adds a wrapping div with a .pre class that
also gets padding added to it. This patch removes the padding from this
wrapping div.
Fixes: QTBUG-133710
Pick-to: 6.9 6.8 6.5
Change-Id: I6411dcda9cfed5f0f82d8bd9ea8dc809b1a3b4d6
Reviewed-by: Venugopal Shivashankar <Venugopal.Shivashankar@qt.io>
- Replace colors in offline-dark.css
- Do not use the note and attention icons in offline templates
Task-number: QTBUG-133761
Pick-to: 6.9 6.9.0 6.8
Change-Id: I55e81d6c3887764542e23c8f85f4d46e273b3885
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
We have divergence in the way we document function, operator and
constructor constraints. About half use \note, while the other
doesn't. Some say "if and only if" while others say just "participates
only if".
So add a qdoc macro, \constraints, to semantically mark up these
constraints. It expands to a section titled `Constraints`, and
uses a predefined sentence (prefix) for constraints.
Documentation for constraints is moved to the end of the comment
blocks to separate them from the rest of the text.
Apply them to all the standard-ish constraint documentation blocks
(grepped for "participate"). I didn't look for other, one-off, ways
documentation authors may have documented constraints, but I'm also
not aware of any.
Re-wrap lines only if the result fits into a single line.
As a drive-by, drop additional "if"s, as in "only if X and -if- Y" to
make the texts work with the `Constraints` section.
Fixes: QTBUG-106871
Pick-to: 6.9 6.8 6.5
Change-Id: I18c2f9f734474017264e49165389f8c9c7f34030
Reviewed-by: Kai Köhne <kai.koehne@qt.io>
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
Reviewed-by: Volker Hilsheimer <volker.hilsheimer@qt.io>
"Android" is trademarked and needs to be referenced in a certain way.
The following steps were taken:
-Created qdoc macro.
-Updated "Qt Android" and "Qt for Android" to use \Q4A in qdoc files.
The macro will need to be adopted in all documentation projects.
Task-number: QAA-2836
Pick-to: 6.9 6.8 6.5
Change-Id: I4b52247a4ed52047242a06404e6d3aa19de9c16c
Reviewed-by: Assam Boudjelthia <assam.boudjelthia@qt.io>
This patch updates the macro AndroidBuildToolsVer to
version 35.0.1.
The version 35.0.1 is used elsewhere, see
b49421a984ac2b203b7995f3787b67184c990089
Amends: 9b475eadfc
Task-number: QTBUG-129462
Pick-to: 6.9 6.8 6.5
Change-Id: Ic15e12c563fa3d16315daa13b6f6b6ef19535954
Reviewed-by: Nicholas Bennett <nicholas.bennett@qt.io>
These warnings are false positives when testing in the CI
when a documentation module containing the base type is meant
to be loaded as a dependency; In the CI, the .index files for
doc dependencies are not available so we see this warning.
Ignore these warnings for now in the global documentation config.
Pick-to: 6.9 6.8
Change-Id: Ic1711bf7389e9f9d4a04e3b72b2c9f8b25539357
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
Insert line breaks in the content the \tab macro expands to. This
produces nicer-looking html and also fixes an issue related to
the post-processing done to the generated files.
Fixes: QTWEBSITE-1202
Pick-to: 6.9 6.8
Change-Id: If4e7f7242f8687ef84ad715744653c4167cf907f
Reviewed-by: Andreas Eliasson <andreas.eliasson@qt.io>
QDoc markup following the \tabcontent macro should start a new
paragraph. As HTML-specific macros are injected directly into
the output, QDoc's doc parser is not aware that the macro should
start a new paragraph.
Turn the macros into generic, non-format-specific macros,
expanding to \div and \enddiv commands that wrap the tab
content.
Pick-to: 6.9 6.8 6.5
Change-Id: Ie8313af391b1a38ef74592acac3198fef5b7b310
Reviewed-by: Venugopal Shivashankar <Venugopal.Shivashankar@qt.io>
The example configuration included a space character that caused a
syntax error parsing the .qdocconf.
Replace the hardcoded qhp `QtDoc` project name with a placeholder.
Pick-to: 6.9 6.8
Change-Id: Iadf3a50e030f02182016ed9832f4f59d29f82c57
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
The new \tm command appends a trademark symbol and links to the
trademark documentation page if `navigation.trademarkspage` variable
is set. As we have such a page in qtdoc repository, set the variable
in the global configuration. This works as all Qt module docs have a
dependency to the `qtdoc` documentation set.
Pick-to: 6.8
Task-number: QTBUG-124393
Change-Id: Iabc6e7e5afe5114eac79947f0feb512458f1c4da
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
The style was already fixed for the "light" offline style,
but the dark offline style was missed.
Amends d39c9d37ad
Task-number: QTBUG-129178
Fixes: QTBUG-131950
Pick-to: 6.8
Change-Id: I4f005cbe1945b8a973fb7bf77fb56b4d59d96b9c
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
Reviewed-by: Kai Köhne <kai.koehne@qt.io>
Add a family of qdoc macros to document the various qHash() overloads
we have.
This patch does not change the \relates of the qHash() functions, they
remain as inconsistent as they have been. Created QTBUG-129815 to
clean things up. Since this author expects the \relates to change in
the future, there are different \qhash commands, and all except
\qhashbuiltin take the class name as an argument, for use in a
centrally-choreographed fix for QTBUG-129815.
As drive-by's, fix:
- missing documentation about Key having to support qHash() in the
associative Qt containers
- drop noexcept and default arguments from \fn lines that needed to
have their argument names changed
- move the QStringView overload from qhash.cpp to qstringview.cpp
(as it \relates to the former)
Fixes: QTBUG-129574
Pick-to: 6.8 6.5
Change-Id: I8e8c2edc27422cbe5823f56baf3a24d7f7050836
Reviewed-by: Ivan Solovev <ivan.solovev@qt.io>
Reviewed-by: Jaishree Vyas <jaishree.vyas@qt.io>
Commit e2ff9e3b99 was adding Q_OBJECT as a qdoc macro to allow to mask
Q_OBJECT calls that are part of the documentation. Anyhow, while qdoc
does allow the underscore in the _definition_ of macros, it doesn't
allow it for the _invocation_. The questionable places should rather
use snippet files.
Fixes: QTBUG-130799
Pick-to: 6.8
Change-Id: I13bac0334b67ba7072946ab7d3f34c7a304c3f84
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
We have some patterns for how to document certain functions, but we
also vary the sentences a lot, and you have to look up one
documentation piece and copy it, essentially. If we ever want to
change them, we end up with shotgun surgery.
So apply DRY to the documentation and start a collection of macros to
help with repetitive C++ class documentation tasks.
The first macro is for member-swap(), and this second patch is for
documentation that used the simplified phrasing ("Swaps this X with \a
other."), which this patch adopts as the text for \memberswap, too,
because it doesn't repeat the macro argument, making it easier to find a
grammatically-fitting argument than in the traditional phrasing.
This doesn't change the documentation, except as follows:
* standardizes on simpified instead of traditional phrasing for docs
that already use the \memberswap macro
* adds the "very fast and never fails" blurb, if it was missing
* changes the function's argument name to `other`, as required by
the macro.
Task-number: QTBUG-129573
Pick-to: 6.8 6.7 6.5 6.2
Change-Id: I1123e783ce0da76c5997ff74007d77504ac5b334
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
Reviewed-by: Ivan Solovev <ivan.solovev@qt.io>
We have some patterns for how to document certain functions, but we
also vary the sentences a lot, and you have to look up one
documentation piece and copy it, essentially. If we ever want to
change them, we end up with shotgun surgery.
So apply DRY to the documentation and start a collection of macros to
help with repetitive C++ class documentation tasks.
The first macro is for member-swap(), and the first patch is for
documentation that used the traditional phrasing ("Swaps the X \a
other with this X.").
This doesn't change the documentation, except as follows:
* adds the "very fast and never fails" blurb, if it was missing
* changes the function's argument name to `other`, as required by
the macro.
Task-number: QTBUG-129573
Pick-to: 6.8 6.7 6.5 6.2
Change-Id: Ib494bd218334724b3b43796ba6f71fb52b83aa94
Reviewed-by: Ivan Solovev <ivan.solovev@qt.io>
This commit fixes the broken layout. Wrapping the divs of
col-1 (content) and col-2(sidebar) classes with a container with
`display:flex` does the job.
Fixes: QTBUG-129178
Pick-to: 6.8
Change-Id: I6867b178e5a1acf6a4fbd5302a857e5f3ca0a62f
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
Reviewed-by: Kai Köhne <kai.koehne@qt.io>
(cherry picked from commit d39c9d37ad)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
The parenthesis ends up without content, and that looks confusing and
broken in e.g. Qt Assistant.
Fixes: QTBUG-120151
Pick-to: 6.8.0 6.8
Change-Id: Ib616741bc0463e8bece481c2a37cd7c3992921ab
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
Use the pre element selector, not the .pre class selector to add correct
padding to pre code blocks and non-code blocks.
Pick-to: 6.8 6.7 6.5 6.2
Change-Id: I14886f44597354c81840a866c75caa62387a7375
Reviewed-by: Tor Arne Vestbø <tor.arne.vestbo@qt.io>
QDoc now has support for a configuration variable, `productname`, the
value of which QDoc's `\since` command prepends to version strings.
Task-number: QTBUG-128911
Change-Id: I03a90764c5886174e2863f50a8e30d2316f02fb5
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
AGP 8.5.2 still throws a warning about not being tested
with Android 15 builds, now 8.6.0 is released and doesn't
have the warning.
Amends b5d8552f2b.
Pick-to: 6.8
Fixes: QTBUG-128648
Task-number: QTBUG-126061
Change-Id: I3d7a4c9c184e1a81f0ebb9431a6e3ca9706d19e9
Reviewed-by: Ville Voutilainen <ville.voutilainen@qt.io>
When generating HTML output, QDoc references CSS styles that control
the visual appearance. For a standard build of Qt's documentation (a
'local' build, if you will), an "offline" style is the default. This
style sheet is maintained in `qtbase.git`.
This style is not particularly well maintained, as it is not the style
in use for documentation published to `doc.qt.io`. As such, some
issues where found as a side-effect of other work. In particular, an
ill-placed background image in the `@media print` CSS instructions was
found in the print dialogue from locally generated content. While
validating the fix, it became clear that the `toc` CSS class was moved
into an obstructing position in the same media type.
Change the `@media print` definition such that:
- The `toc` class is hidden entirely.
Task-number: QTBUG-124162
Fixes: QTBUG-128205
Pick-to: 6.8
Change-Id: Ic427036a698d7fc0e07e9190289e5d2c196885d9
Reviewed-by: Andreas Eliasson <andreas.eliasson@qt.io>
Safiyyah Moosa
Topi Reinio
Konsta Alajärvi
Inkamari Harjula
Marc Mutz
Kai Köhne
Assam Boudjelthia
Venugopal Shivashankar
Leena Miettinen
Thibaut Cuvelier
Paul Wicking
Nicholas Bennett
Andreas Eliasson
Rami Potinkara
Tomi Korpipaa
David Boddie
Eike Ziller
Alexei Cazacov