2f35879649
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>
114 lines
5.1 KiB
Plaintext
114 lines
5.1 KiB
Plaintext
macro.aacute.HTML = "á"
|
|
macro.aacute.DocBook = "á"
|
|
macro.Aring.HTML = "Å"
|
|
macro.Aring.DocBook = "Å"
|
|
macro.aring.HTML = "å"
|
|
macro.aring.DocBook = "å"
|
|
macro.Auml.HTML = "Ä"
|
|
macro.Auml.DocBook = "Ä"
|
|
macro.author = "\\b{Author:}"
|
|
macro.BR.HTML = "<br />"
|
|
macro.BR.DocBook = ""
|
|
macro.copyright.HTML = "©"
|
|
macro.copyright.DocBook = "©"
|
|
macro.eacute.HTML = "é"
|
|
macro.eacute.DocBook = "é"
|
|
macro.gui = "\\b"
|
|
macro.HR.HTML = "<hr />"
|
|
macro.HR.DocBook = ""
|
|
macro.iacute.HTML = "í"
|
|
macro.iacute.DocBook = "í"
|
|
macro.key = "\\b"
|
|
macro.macos = "macOS"
|
|
macro.menu = "\\b"
|
|
macro.oslash.HTML = "ø"
|
|
macro.oslash.DocBook = "ø"
|
|
macro.ouml.HTML = "ö"
|
|
macro.ouml.DocBook = "ö"
|
|
macro.nothing = "\\dontdocument ()"
|
|
macro.nullptr = "\\c{nullptr}"
|
|
macro.QA = "\\e{Qt Assistant}"
|
|
macro.QD = "\\e{Qt Designer}"
|
|
macro.QL = "\\e{Qt Linguist}"
|
|
macro.Q_OBJECT = "Q_OBJECT"
|
|
macro.QQV = "\\e{Qt QML Viewer}"
|
|
macro.QtVersion = "$QT_VERSION"
|
|
macro.QtVer = "$QT_VER"
|
|
macro.param = "\\e"
|
|
macro.raisedaster.HTML = "<sup>*</sup>"
|
|
macro.raisedaster.DocBook = "\\sup{*}"
|
|
macro.rarrow.HTML = "→"
|
|
macro.rarrow.DocBook = "→"
|
|
macro.reg.HTML = "<sup>®</sup>"
|
|
macro.reg.DocBook = "\\sup{®}"
|
|
macro.return = "Returns"
|
|
macro.starslash = "\\c{*/}"
|
|
macro.begincomment = "\\c{/*}"
|
|
macro.endcomment = "\\c{*/}"
|
|
macro.uuml.HTML = "ü"
|
|
macro.uuml.DocBook = "ü"
|
|
macro.mdash.HTML = "—"
|
|
macro.mdash.DocBook = "—"
|
|
macro.pi.HTML = "Π"
|
|
macro.pi.DocBook = "Π"
|
|
macro.beginqdoc.HTML = "/*!"
|
|
macro.endqdoc.HTML = "*/"
|
|
macro.borderedimage = "\\div {class=\"border\"} \\image \1\n\\enddiv"
|
|
macro.examplecategory = "\\meta category {\1}\n\\ingroup {category \1}"
|
|
|
|
macro.beginfloatleft.HTML = "<div style=\"float: left; margin-right: 2em\">"
|
|
macro.beginfloatright.HTML = "<div style=\"float: right; margin-left: 2em\">"
|
|
macro.endfloat.HTML = "</div>"
|
|
macro.clearfloat.HTML = "<br style=\"clear: both\" />"
|
|
macro.emptyspan.HTML = "<span></span>"
|
|
|
|
macro.beginfloatleft.DocBook = ""
|
|
macro.beginfloatright.DocBook = ""
|
|
macro.endfloat.DocBook = ""
|
|
macro.clearfloat.DocBook = ""
|
|
macro.emptyspan.DocBook = ""
|
|
|
|
# Used like \brief, but replicates the sentence also as text.
|
|
# Wrap the entire sentence with {}, for example:
|
|
# \summary {Creates a build target.}
|
|
macro.summary = "\\brief \1\n\n\1\n"
|
|
|
|
# Macros that expand to the major and minor versions based on the QT_VER environment variable
|
|
{macro.QtMajorVersion,macro.QtMinorVersion} = "$QT_VER"
|
|
macro.QtMajorVersion.match = "^(\\d+)\\."
|
|
macro.QtMinorVersion.match = "\\d+\\.(\\d+)"
|
|
|
|
# Embed YouTube content by video ID - Example: \youtube dQw4w9WgXcQ
|
|
# Also requires a <ID>.jpg thumbnail for offline docs. By default, qdoc doesn't copy the thumbnail
|
|
# along with the offline docs, you must specify it manually. In .qdocconf, to do it for all formats
|
|
# at once, add:
|
|
#
|
|
# {HTML.extraimages,qhp.QtDoc.extraFiles, DocBook.extraimages} += images/dQw4w9WgXcQ.jpg
|
|
#
|
|
macro.youtube.HTML = "<div class=\"video\">\n" \
|
|
"<a href=\"https://www.youtube.com/watch/?v=\1\">\n"\
|
|
"<img src=\"images/\1.jpg\"" \
|
|
"title=\"Click to play in a browser\" /></a>\n" \
|
|
"</div>\n"
|
|
|
|
macro.excludefromcreator = "\\meta tag broken"
|
|
|
|
macro.preliminarycmakecommand = "\\note This command is in technology preview and may change in future releases."
|
|
macro.preliminarycmakevariable = "\\note This variable is in technology preview and may change in future releases."
|
|
macro.preliminarycmakeproperty = "\\note This property is in technology preview and may change in future releases."
|
|
|
|
macro.cmakecommandsince = "\n\nThis command was introduced in Qt \1.\n\n"
|
|
macro.cmakevariablesince = "\n\nThis variable was introduced in Qt \1.\n\n"
|
|
macro.cmakepropertysince = "\n\nThis property was introduced in Qt \1.\n\n"
|
|
|
|
macro.cmakecommandandroidonly = "\\note This command should only be called if targeting the Android platform."
|
|
macro.cmakepropertyandroidonly = "\\note This property is used only if targeting the Android platform."
|
|
macro.cmakevariableandroidonly = "\\note This variable is used only if targeting the Android platform."
|
|
|
|
macro.versionlessCMakeCommandsNote = "If \\l{Versionless commands}{versionless commands} are disabled, use \\c{\1} instead. It supports the same set of arguments as this command."
|
|
|
|
macro.cmakepropertywebassemblyonly = "\\note This property is used only if targeting the WebAssembly platform."
|
|
|
|
macro.cmakepropertyiosonly = "\\note This property is used only if targeting iOS."
|
|
macro.cmakevariableiosonly = "\\note This variable is used only if targeting iOS."
|