diff options
| -rw-r--r-- | src/qdoc/doc/qdoc-manual-qdocconf.qdoc | 56 | ||||
| -rw-r--r-- | src/qdoc/doc/qdoc-manual-topiccmds.qdoc | 5 | ||||
| -rw-r--r-- | src/qdoc/generator.cpp | 53 | ||||
| -rw-r--r-- | src/qdoc/generator.h | 10 |
4 files changed, 114 insertions, 10 deletions
diff --git a/src/qdoc/doc/qdoc-manual-qdocconf.qdoc b/src/qdoc/doc/qdoc-manual-qdocconf.qdoc index 0080c6a99..0f38aabce 100644 --- a/src/qdoc/doc/qdoc-manual-qdocconf.qdoc +++ b/src/qdoc/doc/qdoc-manual-qdocconf.qdoc @@ -121,6 +121,8 @@ \li \l {sources.fileextensions-variable} {sources.fileextensions} \li \l {spurious-variable} {spurious} \li \l {tabsize-variable} {tabsize} + \li \l {url-variable} {url} + \li \l {url.examples-variable} {url.examples} \li \l {version-variable} {version} \li \l {versionsym-variable} {versionsym} \li \l {warninglimit-variable} {warninglimit} @@ -1699,7 +1701,59 @@ references to for example Qt classes, the base URL is \c http://doc.qt.io/qt-4.8/. - See also \l indexes. + See also \l indexes and \l {url.examples}. + + \target url.examples-variable + \section1 url.examples + + The \c url.examples variable holds the base URL for the examples + associated with the current project. + + If defined, a link to the example project directory is generated + at the end of each example documentation page. The \c url.examples + variable refers to the root directory of the examples related to + this project; it can be a link to an online repository (starting + with \e http:// or \e https://), or to the local file system + (\c file://). + + If \c url.examples is not defined, QDoc will output a list of + example's files and images instead. + + For example, given these definitions: + + \badcode + url.examples = "https://code.qt.io/cgit/qt/qtbase.git/tree/examples/" + examplesinstallpath = corelib + \endcode + + Then, for the following \l {example-command}{\\example} command: + + \badcode * + /\1! + \example threads/semaphores + ... + \1/ + \endcode + + QDoc generates a link to + \c https://code.qt.io/cgit/qt/qtbase.git/tree/examples/corelib/threads/semaphores. + + If the URL contains more components (for example, a query string) + after the example path, \\1 can be used as a placeholder for the + path: + + \badcode + url.examples = "https://code.qt.io/cgit/qt/qtbase.git/tree/examples/\1?h=$QT_VER" + examplesinstallpath = corelib + \endcode + + Given the same \\example command as above and assuming that + \c $QT_VER expands to \c {5.13}, the generated URL is + \c https://code.qt.io/cgit/qt/qtbase.git/tree/examples/corelib/threads/semaphores?h=5.13. + + \c {url.examples} variable was introduced in QDoc version 5.13. + + See also \l url, \l examplesinstallpath, and \l {example-command}{\\example}. \target howto \section1 How to Support Derived Projects diff --git a/src/qdoc/doc/qdoc-manual-topiccmds.qdoc b/src/qdoc/doc/qdoc-manual-topiccmds.qdoc index 05e7b331b..4e80f8f12 100644 --- a/src/qdoc/doc/qdoc-manual-topiccmds.qdoc +++ b/src/qdoc/doc/qdoc-manual-topiccmds.qdoc @@ -366,7 +366,9 @@ The documentation page will be output to \c {modulename-path-to-example}.html. QDoc will add a list of all the example's source and images files at the end - of the page, unless \l {noautolist-command}{\\noautolist} command is used. + of the page, unless \l {noautolist-command}{\\noautolist} command is used or + the configuration variable \l {url.examples-variable}{url.examples} is defined + for the project. For example, if \l {exampledirs-variable} {exampledirs} contains \c $QTDIR/examples/widgets/imageviewer, then @@ -410,6 +412,7 @@ \b {See also:} \l {generatelist-command}{\\generatelist examplefiles}, \l {noautolist-command}{\\noautolist}, + \l {url.examples-variable}{url.examples}, \l {meta-command}{\\meta} \target externalpage-command diff --git a/src/qdoc/generator.cpp b/src/qdoc/generator.cpp index e5720d5fb..ac5ee56ef 100644 --- a/src/qdoc/generator.cpp +++ b/src/qdoc/generator.cpp @@ -42,6 +42,9 @@ #include "separator.h" #include "tokenizer.h" #include "qdocdatabase.h" +#ifndef QT_BOOTSTRAPPED +# include "QtCore/qurl.h" +#endif QT_BEGIN_NAMESPACE @@ -935,9 +938,14 @@ void Generator::generateBody(const Node *node, CodeMarker *marker) } } + // 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<const ExampleNode*>(node); - if (!en->noAutoList()) { + 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); } @@ -945,6 +953,49 @@ void Generator::generateBody(const Node *node, CodeMarker *marker) } /*! + 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. +*/ +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; +#ifndef QT_BOOTSTRAPPED + link = QUrl(baseUrl).host(); +#endif + if (!link.isEmpty()) + link.prepend(" @ "); + link.prepend("Example project"); + + 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; + + generateText(text, 0, marker); +} + +/*! This function is called when the documentation for an example is being formatted. It outputs a list of files for the example, which can be the example's source files or the list of images used by the diff --git a/src/qdoc/generator.h b/src/qdoc/generator.h index 91ba1d98e..d02c59f44 100644 --- a/src/qdoc/generator.h +++ b/src/qdoc/generator.h @@ -156,14 +156,10 @@ protected: CodeMarker *marker, bool generate, int& numGeneratedAtoms); + void generateLinkToExample(const ExampleNode *en, + CodeMarker *marker, + const QString &baseUrl); void generateFileList(const ExampleNode* en, CodeMarker* marker, bool images); -#if 0 - // Keeping this until usage shows we no longer need it. mws 17/08/2018 - void generateFileList(const PageNode* pn, - CodeMarker* marker, - Node::NodeSubtype subtype, - const QString& regExp); -#endif void generateSince(const Node *node, CodeMarker *marker); void generateStatus(const Node *node, CodeMarker *marker); void generatePrivateSignalNote(const Node* node, CodeMarker* marker); |