Adding some Qt Design Studio macros for global
qtdoc use. This would ensure flexibility for
the documentation writing.
Pick-to: 5.15 6.5 6.6
Task-number: QDS-10142
Change-Id: Id61a68d124aad1b8c8f9e17358fb5990efbab5de
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>
QDoc allows code-expanding macros to be defined so that the user can
abstract away common code in a simple to use command.
Furthermore, macros allows for a different expansion based on the
currently generated format so that format-specific requirements can be
satisfied when required.
When format specific expansions are provided, QDoc considers the
resulting text as if it should be generated verbatim.
The "\raisedaster" macro is used to generate an superscript asterisk.
The macro is provided for both HTML and DocBook.
As the macro has format-specific expansions, the expanded code will be
read verbatim.
Nonetheless, while the HTML expansion expands to actual HTML, the
DocBook expansion expands to an equivalent QDoc code, which will not be
generated correctly.
To avoid the issue, the DocBook version of "\raisedaster" is modified so
that it produces the correct DocBook code.
Change-Id: I3a37838bda885af42f8d93b86ec08126d7146ff9
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
QDoc allows code-expanding macros to be defined so that the user can
abstract away common code in a simple to use command.
Furthermore, macros allows for a different expansion based on the
currently generated format so that format-specific requirements can be
satisfied when required.
Due to a certain bug in QDoc, when generating the DocBook format, QDoc
would expand an HTML specific macro definition when a DocBook specific
one was not provided.
As this bug is now being fixed, the DocBook format will lose some of the
output that it was previously generating.
For example, the "\beginqdoc" and "\endqdoc" macros are defined, for
HTML, to expand to the beginning of block-comment text, "/*!" and ending
of block-comment text, "*/".
To avoid losing the usage of "\beginqdoc" and "\endqdoc`" when
generating DocBook, an equivalent expansion of the macro is now provided
for the DocBook format.
Change-Id: I45fb54f1f56077771c091323a69fd63e09a910eb
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
QDoc allows code-expanding macros to be defined so that the user can
abstract away common code in a simple to use command.
Furthermore, macros allows for a different expansion based on the
currently generated format so that format-specific requirements can be
satisfied when required.
Due to a certain bug in QDoc, when generating the DocBook format, QDoc
would expand an HTML specific macro definition when a DocBook specific
one was not provided.
As this bug is now being fixed, the DocBook format will lose some of the
output that it was previously generating.
For example, the "\youtube" macro is defined, for HTML, so that a
youtube video can be embedded by reference.
To avoid losing the usage of "\youtube" when generating DocBook, an
equivalent version expansion of the macro is now provided for the
DocBook format.
Change-Id: Id74155f2c30b80b5f4490f8451cd8d00535806d6
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
Argument passed to the \ingroup command should not be wrapped in
braces as it's read as-is.
Pick-to: 6.5
Task-number: QTBUG-111891
Change-Id: Ic759af37e8b7e9f60651103b395fdd7e630779c6
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
Examples in Qt's codebase must be tagged with specific categories
such that Qt Creator can group them thematically. This can be done
by way of using the `\meta category` construct in QDoc.
At the same time, we want the generated documentation to group the
examples by the same logic as in Qt Creator. Hence, QDoc was modified
to implicitly add a group for each category that is used in a
`meta category` invocation.
By design, QDoc exposes ways to list groups to users, but no way to list
the \meta command invocations. Letting QDoc implicitly add a group for
categories passed to the \meta command as a side-effect, therefore breaks
with the principle of least surprise and the single responsibility
principle.
An alternative solution makes use of QDoc's existing support for code
generation through macros. This patch introduces the macro
`\examplecategory` as a global macro throughout Qt to achieve the same
effect as the aforementioned change to QDoc. The macro takes an argument
enclosed in curly braces. This argument is the example category name. It's
used as meta information in the manifest files consumed by Qt Creator, and
added as the category group name for the QDoc side at the same time.
The introduction of this macro allows reverting the change to QDoc
itself, while maintaining feature parity for both Qt Creator and the
generated content.
Task-number: QTBUG-111891
Pick-to: 6.5
Change-Id: I311b98168253b45ac456ff3c1824db3d835191a9
Reviewed-by: Luca Di Sera <luca.disera@qt.io>
The same kind of line is required for DocBook as HTML or QHP. This
change makes that requirement clear.
It was suggested by Nicholas Bennett in a change in existing
configuration for this exact line.
Change-Id: I664300f229bac9931c6f1ac4a08bd7c8c42bf37c
Reviewed-by: Nicholas Bennett <nicholas.bennett@qt.io>
Both INITIAL_MEMORY and PTHREAD_POOL_SIZE are settings users can
change, they are not interface settings.
Fixes: QTBUG-100693
Pick-to: 6.3 6.2
Change-Id: Ie1547c7f52c9fe109a313260616705728024b6b8
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>
Reviewed-by: David Skoland <david.skoland@qt.io>
Introduce the qdoc macros \cmakecommandsince, \cmakepropertysince, and
\cmakevariablesince that insert a paragraph akin to the \since context
command.
Example:
\cmakecommandsince 6.3
produces the paragraph
This command was introduced in Qt 6.3
The macro text is wrapped in \n\n to ensure that we always generate a
new paragraph.
Pick-to: 6.2 6.3
Task-number: QTBUG-100212
Change-Id: Id5c8e8812e6b0b915674d108a0e775091e9eacd8
Reviewed-by: Kai Koehne <kai.koehne@qt.io>
This macro expands to the major version of Qt, complementing the
already existing \QtMinorVersion macro.
Pick-to: 6.2 5.15
Change-Id: I64861f8cc50d73f34369311a19b5e554645a4127
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
The macro takes only one parameter, sentences must be wrapped in {}.
Pick-to: 6.2
Fixes: QTBUG-97441
Change-Id: I7177548a32a67d720c2b551d16c09d898b0fda51
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
For normal \page elements, \brief is just showing in the
\generatelist or \annotatedlist commands. Make sure the description
is also visible in the actual CMake command/variable/property
page by defining a \summary macro.
Pick-to: 6.2
Change-Id: I12bc854d547059a2f6309a5922bb0b2a36d4e41c
Reviewed-by: Craig Scott <craig.scott@qt.io>
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
When documenting a CMake command, document the unversioned command
'qt_foo' and use '\versionlessCMakeCommandNote qt6_foo' to refer to the
versioned command. This avoids duplicating the command signature.
Use the new macro where applicable.
Pick-to: 6.2
Task-number: QTBUG-95796
Change-Id: I2e4180fbda0b89acf3d8c036459f591eb2f46475
Reviewed-by: Craig Scott <craig.scott@qt.io>
Reviewed-by: Alexandru Croitor <alexandru.croitor@qt.io>
The vspan was originally added for iframes. They are not needed
(and look weird) for normal images/links.
Pick-to: 6.1
Fixes: QTBUG-92266
Change-Id: I9da2b52234b2e49bc0cdef4bf8f0865fb092bb31
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
There are still other parts of the CMake API that are not yet
documented. This change only addresses qt_add_executable() and the
Android-related commands it uses.
Fixes: QTBUG-88839
Task-number: QTBUG-84482
Pick-to: 6.0
Change-Id: I761b5ce908d1f62284baabe2d414cd37a0efe83d
Reviewed-by: Joerg Bornemann <joerg.bornemann@qt.io>
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>
Reviewed-by: Assam Boudjelthia <assam.boudjelthia@qt.io>
Unlike the QTextBrowser backend, litehtml does not render elements
inside <iframe> correctly. This prevented external links to
YouTube from working in offline documentation.
Move the <iframe> to a macro override specific to online doc builds.
Pick-to: 6.0 6.0.0
Fixes: QTBUG-88975
Change-Id: Iff7828ddeed353620eaa9ac669a3e0c03749daa2
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* Drop deprecation warnings for now-dropped items
* Use the 'qt6' define and a new \nothing doc macro to conditionally
document items on Qt 6
* Add a custom module header for docs that pulls in also Vulkan headers
* Add \internal command for internal classes/functions
* Move QtGUI-related code snippets from widgets to gui docs
Change-Id: Ieb386b96631a49568d09059906d307c45c01d93a
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
CMake's moc file scanning is rather primitive: It will run moc on any
file containing a line that starts with Q_OBJECT (and similar macros).
We have four files in QtBase that contain such a macro at the start
of the line in a qdoc comment. These four files were excluded from
automatic moc handling by cmake, which is not ideal, since this will
silently fail when somebody actually adds a Q_OBJECT macro in code.
This patch introduces a macro Q_OBJECT for qdoc. This macro will be
replaced with Q_OBJECT in the generated documentation. While not nice,
at least a failure to use \Q_OBJECT is noticeable: Moc will warn about
the file.
Change-Id: I829893c1166eee306fe30058d4ea0256affd45ea
Reviewed-by: Simon Hausmann <simon.hausmann@qt.io>
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
Qt for Python users reading the documentation assume that int(0) can
be passed for pointer parameters. Use the newly introduced \nullptr to
disambiguate this.
In a follow-up step, the \nullptr macro can be defined as None
when generating the Qt for Python documentation.
Task-number: PYSIDE-903
Change-Id: I3a45f87175a0668ab5f3f95f0aff409f7e3ef027
Reviewed-by: Cristian Maureira-Fredes <cristian.maureira-fredes@qt.io>
Reviewed-by: Christian Tismer <tismer@stackless.com>
Reviewed-by: Venugopal Shivashankar <Venugopal.Shivashankar@qt.io>
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
Versioning of some QML modules follows the Qt major and minor
version exactly. Add a documentation macro that expands to the short
version string to help automate the QML plugin documentation.
Task-number: QTBUG-67818
Change-Id: I45e7a2a1adfd6a82b828222e49b1d02b7c05897e
Reviewed-by: Venugopal Shivashankar <Venugopal.Shivashankar@qt.io>
Add a global QDoc macro \QtMinorVersion that
expands into the minor version of Qt, or more
specifically, the minor version contained in
the QT_VER environment variable.
The main use case for the new macro is to
document the QML modules whose minor versions
track the minor version of Qt:
\qmlmodule QtQuick 2.\QtMinorVersion
Task-number: QTBUG-67818
Change-Id: I2b4fcbb18de0f8f95718099309090017c237622f
Reviewed-by: Martin Smith <martin.smith@qt.io>
We do add, remove or update third party code in minor releases,
sometimes even in patch level releases. However, the documentation is
supposed to be valid for all existing Qt 5 versions, but doing this for
attributions would require infrastructure we don't have.
Therefore rather make it explicit which Qt version the attributions
apply to. Also mention since when Qt is available under LGPLv3
(starting with Qt 5.4).
Task-number: QTBUG-65665
Change-Id: I328b5bf0c143f78ea61aad51f0644c3cbb6dee49
Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
This macro adds a \youtube <ID> command that embeds a YouTube link
into the documentation.
The video container scales to a specified percentage of the available
horizontal area. It assumes a source aspect ratio of 16:9, but looks
acceptable with other ratios.
For backends that do not support <iframe> (e.g. QTextBrowser), shows
a clickable video thumbnail that open the YouTube link in an external
browser window. Unfortunately, QTextBrowser cannot load images from
a remote URL, so we need to store a thumbnail image in the .qch file.
Change-Id: I3a3a0c5a20dd90e5cec6357ba70a23ee47dbe825
Reviewed-by: Mitch Curtis <mitch.curtis@qt.io>
Reviewed-by: Venugopal Shivashankar <Venugopal.Shivashankar@qt.io>
This macro is used similarly to the \image command; it wraps the image
in a div with class attribute 'border' that allows additional styling
in CSS.
Change-Id: I94271074378d79f0e52f1f5a4715a1f84e0254dc
Reviewed-by: Mitch Curtis <mitch.curtis@qt.io>
As of version 10.12 (Sierra), the name of Apple's desktop operating
system will be macOS. Change the occurrences where the Mac platform
is discussed to use a macro \macos, which expands to 'macOS'. This
helps with adapting to future renaming.
Update the instructions on mac-specific Q_OS_* macro usage.
Add a \target for the old 'Qt for OS X' topic to keep links working
for other documentation modules that try to link with the old name.
Change-Id: Id33fb0cd985df702a4ae4efb4c5fd428e77d9b85
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>
Since the \br was promoted from a macro to a QDoc command, its output
has been enclosed in extra paragraph end/start tags, adding to the
visible vertical space.
This change fixes the issue by not closing the paragraph when QDoc
encounters a \br command.
Also removes the now-obsolete \br and \hr macros, as they are both
proper commands. \BR and \HR substitute macros are kept.
Task-number: QTBUG-37361
Change-Id: Iabbefb6e79268419792ccba42386f6342ccd175d
Reviewed-by: Martin Smith <martin.smith@digia.com>
These macros were previously defined for QDoc manual.
This change adds them to global macros.qdocconf so
they can be used everywhere.
Change-Id: I4fdf5a103ecfb356719951a7d0c6fbd35c887744
Reviewed-by: Jerome Pasion <jerome.pasion@digia.com>
The module documentation require these definitions.
Change-Id: Iecef3df5edad761d8c5f67b14783e13952ab2dbb
Reviewed-by: Martin Smith <martin.smith@digia.com>
