From ebb7a33ed90264a6b82c7978b58ce71b5c7cf042 Mon Sep 17 00:00:00 2001
From: Topi Reinio <topi.reinio@qt.io>
Date: Thu, 22 Jun 2017 16:04:13 +0200
Subject: [PATCH] qdoc: Improve example file listing
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
At the end of \example documentation page, qdoc lists all the files
that are part of the example project. This commit does the
following improvements:
- Sort the example files based on path name
- Introduce '\generatelist examplefiles [regexp]', which
lists the files (optionally, only those that match regexp)
at the specified location.
- Enable \noautolist for example pages, to skip generating the
the file list at the end.
Change-Id: Ic9ae70f9f7de166d314ae489a7bab9a935949fc3
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
---
src/qdoc/doc/qdoc-manual-markupcmds.qdoc | 28 ++++++++++++++++++
src/qdoc/generator.cpp | 37 +++++++++++++++++++-----
src/qdoc/generator.h | 3 +-
src/qdoc/htmlgenerator.cpp | 10 +++++++
src/qdoc/node.cpp | 2 +-
src/qdoc/node.h | 10 +++----
6 files changed, 76 insertions(+), 14 deletions(-)
diff --git a/src/qdoc/doc/qdoc-manual-markupcmds.qdoc b/src/qdoc/doc/qdoc-manual-markupcmds.qdoc
index 24dc7158a..4e4641ecb 100644
--- a/src/qdoc/doc/qdoc-manual-markupcmds.qdoc
+++ b/src/qdoc/doc/qdoc-manual-markupcmds.qdoc
@@ -3544,6 +3544,30 @@
A support class is identified in the \\class comment with the \l
{compat-command} {\\compat} command.
+ \section2 \c {examplefiles [regular_expression]}
+
+ The \c examplefiles argument lists the files that are part of
+ an example project. The optional second argument is a regular
+ expression; if provided, only the files whose path matches with
+ the regular expression are listed.
+
+ The \c examplefiles argument can be only used within example
+ documentation (see \l {example-command}{\\example}), and is
+ typically used together with the \l {noautolist-command}{\\noautolist}
+ command.
+
+ \section2 \c {exampleimages [regular_expression]}
+
+ The \c exampleimages argument lists the images that are part of
+ an example project. The optional second argument is a regular
+ expression; if provided, only the image files whose path matches
+ with the regular expression are listed.
+
+ The \c exampleimages argument can be only used within example
+ documentation (see \l {example-command}{\\example}), and is
+ typically used together with the \l {noautolist-command}{\\noautolist}
+ command.
+
\section2 \c functionindex
The \c functionindex argument provides a complete alphabetical
@@ -3953,6 +3977,10 @@
This command was introduced in QDoc 5.6.
+ Since Qt 5.10, this command can be applied also to \l{example-command}
+ {\\example} documentation, where it causes the automatically generated
+ list of files and images belonging to an example project to be omitted.
+
\target omit-command
\section1 \\omit
diff --git a/src/qdoc/generator.cpp b/src/qdoc/generator.cpp
index eaf1a6133..338f8a9ce 100644
--- a/src/qdoc/generator.cpp
+++ b/src/qdoc/generator.cpp
@@ -960,7 +960,7 @@ void Generator::generateBody(const Node *node, CodeMarker *marker)
if (node->isDocumentNode()) {
const DocumentNode *dn = static_cast<const DocumentNode *>(node);
- if (dn->isExample()) {
+ if (dn->isExample() && !dn->noAutoList()) {
generateExampleFiles(dn, marker);
}
else if (dn->docSubtype() == Node::File) {
@@ -983,8 +983,8 @@ void Generator::generateExampleFiles(const DocumentNode *dn, CodeMarker *marker)
{
if (dn->childNodes().isEmpty())
return;
- generateFileList(dn, marker, Node::File, QString("Files:"));
- generateFileList(dn, marker, Node::Image, QString("Images:"));
+ generateFileList(dn, marker, Node::File);
+ generateFileList(dn, marker, Node::Image);
}
void Generator::generateDocumentNode(DocumentNode* /* dn */, CodeMarker* /* marker */)
@@ -1005,16 +1005,39 @@ void Generator::generateCollectionNode(CollectionNode* , CodeMarker* )
void Generator::generateFileList(const DocumentNode* dn,
CodeMarker* marker,
Node::DocSubtype subtype,
- const QString& tag)
+ const QString& regExp)
{
int count = 0;
Text text;
OpenedList openedList(OpenedList::Bullet);
+ QString tag;
+
+ NodeList children(dn->childNodes());
+ std::sort(children.begin(), children.end(), Generator::compareNodes);
+ if (!regExp.isEmpty()) {
+ QRegExp re(regExp);
+ QMutableListIterator<Node*> i(children);
+ while (i.hasNext()) {
+ if (!re.exactMatch(i.next()->name()))
+ i.remove();
+ }
+ }
+ if (children.size() > 1) {
+ switch (subtype) {
+ default:
+ case Node::File:
+ tag = "Files:";
+ break;
+ case Node::Image:
+ tag = "Images:";
+ break;
+ }
+ text << Atom::ParaLeft << tag << Atom::ParaRight;
+ }
- text << Atom::ParaLeft << tag << Atom::ParaRight
- << Atom(Atom::ListLeft, openedList.styleString());
+ text << Atom(Atom::ListLeft, openedList.styleString());
- foreach (const Node* child, dn->childNodes()) {
+ foreach (const Node* child, children) {
if (child->docSubtype() == subtype) {
++count;
QString file = child->name();
diff --git a/src/qdoc/generator.h b/src/qdoc/generator.h
index a3c34eaba..4709ad129 100644
--- a/src/qdoc/generator.h
+++ b/src/qdoc/generator.h
@@ -153,7 +153,7 @@ protected:
void generateFileList(const DocumentNode* dn,
CodeMarker* marker,
Node::DocSubtype subtype,
- const QString& tag);
+ const QString& regExp = QString());
void generateSince(const Node *node, CodeMarker *marker);
void generateStatus(const Node *node, CodeMarker *marker);
void generatePrivateSignalNote(const Node* node, CodeMarker* marker);
@@ -230,6 +230,7 @@ private:
static QmlTypeNode* qmlTypeContext_;
void generateReimplementedFrom(const FunctionNode *func, CodeMarker *marker);
+ static bool compareNodes(Node *a, Node *b) { return (a->name() < b->name()); }
protected:
const Config* config_;
diff --git a/src/qdoc/htmlgenerator.cpp b/src/qdoc/htmlgenerator.cpp
index be6617501..10199d7df 100644
--- a/src/qdoc/htmlgenerator.cpp
+++ b/src/qdoc/htmlgenerator.cpp
@@ -709,6 +709,16 @@ int HtmlGenerator::generateAtom(const Atom *atom, const Node *relative, CodeMark
generateAnnotatedList(relative, marker, cn->members());
}
}
+ else if (atom->string().startsWith("examplefiles") ||
+ atom->string().startsWith("exampleimages")) {
+ if (relative->isExample()) {
+ Node::DocSubtype subType = (atom->string().mid(7,5) == "image") ? Node::Image : Node::File;
+ generateFileList(static_cast<const DocumentNode*>(relative), marker, subType,
+ atom->string().mid(atom->string().indexOf(" ")).trimmed());
+ }
+ else
+ relative->location().warning(QString("'\\generatelist \1' can only be used with '\\example' topic command").arg(atom->string()));
+ }
else if (atom->string() == QLatin1String("classhierarchy")) {
generateClassHierarchy(relative, qdb_->getCppClasses());
}
diff --git a/src/qdoc/node.cpp b/src/qdoc/node.cpp
index 6d83ba631..9919317f2 100644
--- a/src/qdoc/node.cpp
+++ b/src/qdoc/node.cpp
@@ -1213,7 +1213,7 @@ NodeList Aggregate::overloads(const QString &funcName) const
given \a type and having the given \a parent and \a name.
*/
Aggregate::Aggregate(NodeType type, Aggregate *parent, const QString& name)
- : Node(type, parent, name)
+ : Node(type, parent, name), noAutoList_(false)
{
switch (type) {
case Class:
diff --git a/src/qdoc/node.h b/src/qdoc/node.h
index 2de9e2e5b..33cdd3c1a 100644
--- a/src/qdoc/node.h
+++ b/src/qdoc/node.h
@@ -423,7 +423,8 @@ public:
void setOutputSubdirectory(const QString& t) Q_DECL_OVERRIDE;
const NodeMap& primaryFunctionMap() { return primaryFunctionMap_; }
const QMap<QString, NodeList>& secondaryFunctionMap() { return secondaryFunctionMap_; }
-
+ bool noAutoList() const { return noAutoList_; }
+ virtual void setNoAutoList(bool b) Q_DECL_OVERRIDE { noAutoList_ = b; }
protected:
Aggregate(NodeType type, Aggregate* parent, const QString& name);
@@ -444,6 +445,7 @@ private:
NodeMap childMap_;
NodeMap primaryFunctionMap_;
QMap<QString, NodeList> secondaryFunctionMap_;
+ bool noAutoList_;
};
class LeafNode : public Node
@@ -1151,7 +1153,7 @@ class CollectionNode : public Aggregate
Aggregate* parent,
const QString& name,
Genus genus)
- : Aggregate(type, parent, name), seen_(false), noAutoList_(false)
+ : Aggregate(type, parent, name), seen_(false)
{
setPageType(Node::OverviewPage);
setGenus(genus);
@@ -1194,12 +1196,10 @@ class CollectionNode : public Aggregate
void markSeen() { seen_ = true; }
void markNotSeen() { seen_ = false; }
- bool noAutoList() const { return noAutoList_; }
- virtual void setNoAutoList(bool b) Q_DECL_OVERRIDE { noAutoList_ = b; }
+
private:
bool seen_;
- bool noAutoList_;
QString title_;
QString subtitle_;
NodeList members_;
--
GitLab