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 5c0b08a20dd14f7fd8632495aa911fe427f58f7f.
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: 9b475eadfcf04194a094454f65295c3a456000a4
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 d39c9d37ade8d74e534952e47061168be8904fc7
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 e2ff9e3b9957 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 d39c9d37ade8d74e534952e47061168be8904fc7)
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 b5d8552f2baab56457d3f39f6b2915c72447b702.
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>
- The docs were restructured in v. 13.0 and 14.0, so most headings
changed, some topics were removed and lots of topics were added
- Use the macro \QC
- Fix the broken links in qtbase
Change-Id: Ic173a3e9a1c80322162c3feb277098de2a9f1cc6
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
The previous description was too bare bones and did not allow further
processing of the file. The new implementation gives more information
and is consistent with what the standard xslTNG style sheets expect
(https://github.com/docbook/xslTNG/blob/2.2.0/src/test/resources/xml/mo-1/preface.xml). Previous versions of the style sheets do not support video embedding.
Change-Id: I1604858b6ad6254c4006470521a30cc0acd7b136
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
These macros generate a a three-column grid of items in online
documentation.
These make for a clutter-free and more visually pleasing result
in many cases, compared to a standard \table layout.
For compatibility reasons, these macros continue to output a table
structure in offline documentation builds.
Task-number: QTWEBSITE-1144
Change-Id: Iab994b383f488dbd225c6a04d64cf41e2dbb20e9
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
Updated Gradle to 8.7
Updated AGP to 8.4.0
Updated same versions in examples and docs macros
Task-number: QTBUG-113383
Change-Id: Ib2e841f2e57e576c5d689a208a275ce5e9e4b80f
Reviewed-by: Assam Boudjelthia <assam.boudjelthia@qt.io>
Bump the minimum supported Android API from 23 to 28 i.e.
Android Oreo 9. This is done to focus more and more on
recent versions.
Fixes: QTBUG-125023
Task-number: QTBUG-124890
Change-Id: I4d510b771f413e5711dd44de454211e019c63db6
Reviewed-by: Heikki Halmet <heikki.halmet@qt.io>
This works better with the current Gradle 8.3 and supports
Android api 34 builds.
Task-number: QTBUG-106907
Change-Id: I816a1aa163a9aee0a5859872129cff62f81a2dea
Reviewed-by: Tinja Paavoseppä <tinja.paavoseppa@qt.io>
Allow setting the package name directly from CMake properties.
If the package name is not set manually under AndroidManifest.xml
nor build.gradle, then the value set by this property is used.
The value is passed to build.gradle as "namespace" which is the
way to set the package name after AGP 7.4 instead of
AndroidManifest.xml "package" attribute.
Task-number: QTBUG-106907
Change-Id: I94bd73c294d751eabfd96c0a10a6b3ff270d8137
Reviewed-by: Tinja Paavoseppä <tinja.paavoseppa@qt.io>
