From 3f3cf9dd93bfcb6c8989afa45f391633d007c8ce Mon Sep 17 00:00:00 2001 From: Topi Reinio Date: Thu, 12 Sep 2019 00:38:49 +0200 Subject: qdoc: WebXML output format: Fix issues with example pages Since QDoc no longer stores example files as nodes in its tree, the WebXMLGenerator failed to generate output for those files. Fix this by generating those pages explicitly as needed, overriding functions from the Generator base class. Prevent QDocIndexFiles from writing nested elements when WebXMLGenerator is in use, as that does not work as expected with shiboken2. Fixes: PYSIDE-1088 Change-Id: I01c2af2391726f448271fdb810ffc3da923caca5 Reviewed-by: Venugopal Shivashankar Reviewed-by: Paul Wicking --- src/qdoc/generator.cpp | 125 ++++++++++++++++++++++++++++++++----------------- 1 file changed, 81 insertions(+), 44 deletions(-) (limited to 'src/qdoc/generator.cpp') diff --git a/src/qdoc/generator.cpp b/src/qdoc/generator.cpp index de9976502..d5caa8bd0 100644 --- a/src/qdoc/generator.cpp +++ b/src/qdoc/generator.cpp @@ -447,9 +447,13 @@ QString Generator::fileBase(const Node *node) const /*! Constructs an href link from an example file name, which - is a path to the example file. + is a path to the example file. If \a fileExtension is + empty (default value), retrieve the file extension from + the generator. */ -QString Generator::linkForExampleFile(const QString &path, const Node *parent) +QString Generator::linkForExampleFile(const QString &path, + const Node *parent, + const QString &fileExt) { QString link = path; QString modPrefix(parent->physicalModuleName()); @@ -460,10 +464,30 @@ QString Generator::linkForExampleFile(const QString &path, const Node *parent) QString res; transmogrify(link, res); res.append(QLatin1Char('.')); - res.append(fileExtension()); + res.append(fileExt); + if (fileExt.isEmpty()) + res.append(fileExtension()); return res; } +/*! + Helper function to construct a title for a file or image page + included in an example. +*/ +QString Generator::exampleFileTitle(const ExampleNode *relative, + const QString &fileName) +{ + QString suffix; + if (relative->files().contains(fileName)) + suffix = QLatin1String(" Example File"); + else if (relative->images().contains(fileName)) + suffix = QLatin1String(" Image File"); + else + return suffix; + + return fileName.mid(fileName.lastIndexOf(QLatin1Char('/')) + 1) + suffix; +} + /*! If the \a node has a URL, return the URL as the file name. Otherwise, construct the file name from the fileBase() and @@ -939,62 +963,75 @@ void Generator::generateBody(const Node *node, CodeMarker *marker) } } } + generateRequiredLinks(node, marker); +} + +/*! + Generates either a link to the project folder for example \a node, or a list + of links files/images if 'url.examples config' variable is not defined. + + Does nothing for non-example nodes. +*/ +void Generator::generateRequiredLinks(const Node *node, CodeMarker *marker) +{ + if (!node->isExample()) + return; + + const ExampleNode *en = static_cast(node); + QString exampleUrl = config()->getString(CONFIG_URL + Config::dot + CONFIG_EXAMPLES); - // For examples, generate either a link to the project directory - // (if url.examples is defined), or a list of files/images. - if (node->isExample()) { - const ExampleNode* en = static_cast(node); - QString exampleUrl = config()->getString(CONFIG_URL + Config::dot + CONFIG_EXAMPLES); - if (!exampleUrl.isEmpty()) { - generateLinkToExample(en, marker, exampleUrl); - } else if (!en->noAutoList()) { - generateFileList(en, marker, false); - generateFileList(en, marker, true); + if (exampleUrl.isEmpty()) { + if (!en->noAutoList()) { + generateFileList(en, marker, false); // files + generateFileList(en, marker, true); // images } + } else { + generateLinkToExample(en, marker, exampleUrl); } } /*! - Generates a link to the project folder for example node \a en. - \a baseUrl is the base URL - path information is available in - the example node's name() and 'examplesinstallpath' configuration - variable. + Generates an external link to the project folder for example \a node. + The path to the example is appended to \a baseUrl string, or to a + specific location within the string marked with the placeholder '\1' + character. */ void Generator::generateLinkToExample(const ExampleNode *en, CodeMarker *marker, const QString &baseUrl) { - Text text; - QString exampleUrl(baseUrl); - - if (!exampleUrl.contains("\1")) { - if (!exampleUrl.endsWith("/")) - exampleUrl += "/"; - exampleUrl += "\1"; - } - - // Name of the example node is the path, relative to install path - QStringList path = QStringList() - << config()->getString(CONFIG_EXAMPLESINSTALLPATH) - << en->name(); - path.removeAll({}); - - QString link; + QString exampleUrl(baseUrl); + QString link; #ifndef QT_BOOTSTRAPPED - link = QUrl(baseUrl).host(); + link = QUrl(exampleUrl).host(); #endif - if (!link.isEmpty()) - link.prepend(" @ "); - link.prepend("Example project"); + if (!link.isEmpty()) + link.prepend(" @ "); + link.prepend("Example project"); + + const QLatin1Char separator('/'); + const QLatin1Char placeholder('\1'); + if (!exampleUrl.contains(placeholder)) { + if (!exampleUrl.endsWith(separator)) + exampleUrl += separator; + exampleUrl += placeholder; + } - text << Atom::ParaLeft - << Atom(Atom::Link, exampleUrl.replace("\1", path.join("/"))) - << Atom(Atom::FormattingLeft, ATOM_FORMATTING_LINK) - << Atom(Atom::String, link) - << Atom(Atom::FormattingRight, ATOM_FORMATTING_LINK) - << Atom::ParaRight; + // Construct a path to the example; / + QStringList path = QStringList() + << config()->getString(CONFIG_EXAMPLESINSTALLPATH) + << en->name(); + path.removeAll({}); + + Text text; + text << Atom::ParaLeft + << Atom(Atom::Link, exampleUrl.replace(placeholder, path.join(separator))) + << Atom(Atom::FormattingLeft, ATOM_FORMATTING_LINK) + << Atom(Atom::String, link) + << Atom(Atom::FormattingRight, ATOM_FORMATTING_LINK) + << Atom::ParaRight; - generateText(text, 0, marker); + generateText(text, 0, marker); } /*! -- cgit v1.2.3