From cd50765264adac52dc7ace48b0f339c0b13f76fc Mon Sep 17 00:00:00 2001 From: Topi Reinio Date: Mon, 27 Jan 2020 23:45:59 +0100 Subject: qdoc: Allow per-example override of install path The 'examplesinstallpath' configuration variable assumes that all examples - once installed - are located under a common root path. Add a parameter 'installpath', recognized by the \meta command, which can be used for setting the install path for specified examples. Improve the test for examples-manifest.xml to cover the \meta command usage. Task-number: QTBUG-81360 Change-Id: Ibb525a48958005fb3a589ef2d9d212091829231f Reviewed-by: Levon Sargsyan Reviewed-by: Paul Wicking --- src/qdoc/doc/qdoc-manual-markupcmds.qdoc | 16 +++++++++++++ src/qdoc/doc/qtgui-qdocconf.qdoc | 8 +++++-- src/qdoc/generator.cpp | 6 +++-- src/qdoc/htmlgenerator.cpp | 18 +++++++++----- .../qdoc/generatedoutput/examples-qhp.qdocconf | 2 ++ .../expected_output/examples-manifest.xml | 6 ++--- .../html/test-componentset-example.webxml | 28 ++++++++++++++++++++-- .../expected_output/test-componentset-example.html | 10 ++++++++ .../generatedoutput/qml/componentset/examples.qdoc | 4 ++++ tests/auto/qdoc/generatedoutput/testqml.qdocconf | 2 ++ 10 files changed, 85 insertions(+), 15 deletions(-) diff --git a/src/qdoc/doc/qdoc-manual-markupcmds.qdoc b/src/qdoc/doc/qdoc-manual-markupcmds.qdoc index 9c11fdd49..51aa3c2cc 100644 --- a/src/qdoc/doc/qdoc-manual-markupcmds.qdoc +++ b/src/qdoc/doc/qdoc-manual-markupcmds.qdoc @@ -3888,6 +3888,22 @@ This would result in the following tags: \e {tutorial,basic,hello,world}. Common words such as \e example are ignored. + \b {Example Install Paths} + + The \\meta command combined with an argument \c installpath specifies the + location of an installed example. This value overrides the one that is set + using the \c examplesinstallpath configuration variable. + + \badcode + / *! + \example helloworld + \title Hello World Example + \meta {installpath} {tutorials} + * / + \endcode + + See also \l {examplesinstallpath}. + \target noautolist-command \section1 \\noautolist diff --git a/src/qdoc/doc/qtgui-qdocconf.qdoc b/src/qdoc/doc/qtgui-qdocconf.qdoc index eaed76c67..4161c2917 100644 --- a/src/qdoc/doc/qtgui-qdocconf.qdoc +++ b/src/qdoc/doc/qtgui-qdocconf.qdoc @@ -137,7 +137,7 @@ to content listed in the index. \note QDoc omits this value when the -installdir argument is specified when running QDoc. -\keyword examplesinstallpath +\target examplesinstallpath \badcode examplesinstallpath = gui @@ -150,7 +150,11 @@ installed in the \e gui directory under the parent examples directory \note The examplepath variable has to match the example directory specified in \c exampledirs. -\b {See also}: \l {exampledirs}. +\note It is possible to override the \c exampleinstallpath for a specific + \l {example-command}{\\example} using the \l {meta-command}{\\meta} + command. + +\b {See also}: \l {exampledirs} and \l {meta-command}{\\meta}. \badcode qhp.projects = QtGui diff --git a/src/qdoc/generator.cpp b/src/qdoc/generator.cpp index 846db961a..46d3ad453 100644 --- a/src/qdoc/generator.cpp +++ b/src/qdoc/generator.cpp @@ -960,8 +960,10 @@ void Generator::generateLinkToExample(const ExampleNode *en, CodeMarker *marker, } // Construct a path to the example; / - QStringList path = QStringList() - << config()->getString(CONFIG_EXAMPLESINSTALLPATH) << en->name(); + QString pathRoot = en->doc().metaTagMap().value(QLatin1String("installpath")); + if (pathRoot.isEmpty()) + pathRoot = config()->getString(CONFIG_EXAMPLESINSTALLPATH); + QStringList path = QStringList() << pathRoot << en->name(); path.removeAll({}); Text text; diff --git a/src/qdoc/htmlgenerator.cpp b/src/qdoc/htmlgenerator.cpp index 9f29d099c..8d6d5000f 100644 --- a/src/qdoc/htmlgenerator.cpp +++ b/src/qdoc/htmlgenerator.cpp @@ -219,8 +219,6 @@ void HtmlGenerator::initializeGenerator(const Config &config) + QLatin1Char('/'); readManifestMetaContent(config); examplesPath = config.getString(CONFIG_EXAMPLESINSTALLPATH); - if (!examplesPath.isEmpty()) - examplesPath += QLatin1Char('/'); // Retrieve the config for the navigation bar homepage = config.getString(CONFIG_NAVIGATION + Config::dot + CONFIG_HOMEPAGE); @@ -3892,6 +3890,14 @@ void HtmlGenerator::generateManifestFile(const QString &manifest, const QString } else if (en->name().startsWith("demos")) { continue; } + + // Retrieve the install path specified with \meta command, + // or fall back to the one defined in .qdocconf + QString installPath = en->doc().metaTagMap().value(QLatin1String("installpath")); + if (installPath.isEmpty()) + installPath = examplesPath; + if (!installPath.isEmpty() && !installPath.endsWith(QLatin1Char('/'))) + installPath += QLatin1Char('/'); // attributes that are always written for the element usedAttributes.clear(); usedAttributes << "name" @@ -3911,7 +3917,7 @@ void HtmlGenerator::generateManifestFile(const QString &manifest, const QString } if (!proFiles.isEmpty()) { if (proFiles.size() == 1) { - writer.writeAttribute("projectPath", examplesPath + proFiles[0]); + writer.writeAttribute("projectPath", installPath + proFiles[0]); } else { QString exampleName = en->name().split('/').last(); bool proWithExampleNameFound = false; @@ -3920,13 +3926,13 @@ void HtmlGenerator::generateManifestFile(const QString &manifest, const QString || proFiles[j].endsWith(QStringLiteral("%1/%1.qmlproject").arg(exampleName)) || proFiles[j].endsWith( QStringLiteral("%1/%1.pyproject").arg(exampleName))) { - writer.writeAttribute("projectPath", examplesPath + proFiles[j]); + writer.writeAttribute("projectPath", installPath + proFiles[j]); proWithExampleNameFound = true; break; } } if (!proWithExampleNameFound) - writer.writeAttribute("projectPath", examplesPath + proFiles[0]); + writer.writeAttribute("projectPath", installPath + proFiles[0]); } } if (!en->imageFileName().isEmpty()) { @@ -4064,7 +4070,7 @@ void HtmlGenerator::generateManifestFile(const QString &manifest, const QString if (--it == filesToOpen.constBegin()) { writer.writeAttribute(QStringLiteral("mainFile"), QStringLiteral("true")); } - writer.writeCharacters(examplesPath + it.value()); + writer.writeCharacters(installPath + it.value()); writer.writeEndElement(); } diff --git a/tests/auto/qdoc/generatedoutput/examples-qhp.qdocconf b/tests/auto/qdoc/generatedoutput/examples-qhp.qdocconf index 816d1d1a4..b4598476e 100644 --- a/tests/auto/qdoc/generatedoutput/examples-qhp.qdocconf +++ b/tests/auto/qdoc/generatedoutput/examples-qhp.qdocconf @@ -1,6 +1,8 @@ # QML test includes a documented example include(testqml.qdocconf) +examplesinstallpath = test + # Configure .qhp generation qhp.projects = Test diff --git a/tests/auto/qdoc/generatedoutput/expected_output/examples-manifest.xml b/tests/auto/qdoc/generatedoutput/expected_output/examples-manifest.xml index 330923033..7f206d0e8 100644 --- a/tests/auto/qdoc/generatedoutput/expected_output/examples-manifest.xml +++ b/tests/auto/qdoc/generatedoutput/expected_output/examples-manifest.xml @@ -1,9 +1,9 @@ - - - documentation,qml,test + + + documentation,qml,sample,test diff --git a/tests/auto/qdoc/generatedoutput/expected_output/html/test-componentset-example.webxml b/tests/auto/qdoc/generatedoutput/expected_output/html/test-componentset-example.webxml index 8689d2e76..29ed944ba 100644 --- a/tests/auto/qdoc/generatedoutput/expected_output/html/test-componentset-example.webxml +++ b/tests/auto/qdoc/generatedoutput/expected_output/html/test-componentset-example.webxml @@ -1,12 +1,13 @@ - + - + + Example for documenting QML types. This example demonstrates one of the ways to document QML types. In particular, there are sample types that are documented with QDoc commands comments. There are documentation comments for the QML types and their public interfaces. The types are grouped into a module, the UI Components module. The uicomponents.qdoc file generates the overview page for the UI Components module page. @@ -32,6 +33,29 @@ An aliased property of type int. QML Types with C++ Implementation This example only demonstrates the documentation for types in QML files, but the regular QML commands may be placed inside C++ classes to define the public API of the QML type. + Files: + + + + componentset/ProgressBar.qml + + + + + componentset/Switch.qml + + + + + componentset/TabWidget.qml + + + + + componentset/componentset.pro + + + diff --git a/tests/auto/qdoc/generatedoutput/expected_output/test-componentset-example.html b/tests/auto/qdoc/generatedoutput/expected_output/test-componentset-example.html index faf632bea..8b792090f 100644 --- a/tests/auto/qdoc/generatedoutput/expected_output/test-componentset-example.html +++ b/tests/auto/qdoc/generatedoutput/expected_output/test-componentset-example.html @@ -19,6 +19,9 @@

QML Documentation Example

+ +

Example for documenting QML types.

+

This example demonstrates one of the ways to document QML types.

@@ -42,6 +45,13 @@ An aliased property of type int

QML Types with C++ Implementation

This example only demonstrates the documentation for types in QML files, but the regular QML commands may be placed inside C++ classes to define the public API of the QML type.

+

Files:

+
diff --git a/tests/auto/qdoc/generatedoutput/qml/componentset/examples.qdoc b/tests/auto/qdoc/generatedoutput/qml/componentset/examples.qdoc index 7c780eca8..2f56c221c 100644 --- a/tests/auto/qdoc/generatedoutput/qml/componentset/examples.qdoc +++ b/tests/auto/qdoc/generatedoutput/qml/componentset/examples.qdoc @@ -28,6 +28,10 @@ /*! \example componentset \title QML Documentation Example + \brief Example for documenting QML types. + + \meta tag {test,sample} + \meta installpath tutorials This example demonstrates one of the ways to document QML types. diff --git a/tests/auto/qdoc/generatedoutput/testqml.qdocconf b/tests/auto/qdoc/generatedoutput/testqml.qdocconf index c469bde06..f618fe1b8 100644 --- a/tests/auto/qdoc/generatedoutput/testqml.qdocconf +++ b/tests/auto/qdoc/generatedoutput/testqml.qdocconf @@ -16,5 +16,7 @@ excludedirs = ./bug80259 sources.fileextensions = "*.qml *.cpp *.qdoc" headers.fileextensions = "*.h" +examples.fileextensions = "*.qml" + macro.begincomment = "\\c{/*}" macro.QDocTestVer = "1.1" -- cgit v1.2.3