1// Copyright (C) 2019 Thibaut Cuvelier
2// Copyright (C) 2021 The Qt Company Ltd.
3// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GPL-3.0-only WITH Qt-GPL-exception-1.0
4
5#ifndef DOCBOOKGENERATOR_H
6#define DOCBOOKGENERATOR_H
7
8#include "codemarker.h"
9#include "config.h"
10#include "xmlgenerator.h"
11#include "filesystem/fileresolver.h"
12
13#include <QtCore/qhash.h>
14#include <QtCore/qxmlstream.h>
15
16QT_BEGIN_NAMESPACE
17
18class Aggregate;
19class ExampleNode;
20class FunctionNode;
21
22class DocBookGenerator : public XmlGenerator
23{
24public:
25 explicit DocBookGenerator(FileResolver& file_resolver);
26
27 void initializeGenerator() override;
28 QString format() override;
29
30protected:
31 [[nodiscard]] QString fileExtension() const override;
32 void generateDocumentation(Node *node) override;
33 using Generator::generateCppReferencePage;
34 void generateCppReferencePage(Node *node);
35 using Generator::generatePageNode;
36 void generatePageNode(PageNode *pn);
37 using Generator::generateQmlTypePage;
38 void generateQmlTypePage(QmlTypeNode *qcn);
39 using Generator::generateCollectionNode;
40 void generateCollectionNode(CollectionNode *cn);
41 using Generator::generateGenericCollectionPage;
42 void generateGenericCollectionPage(CollectionNode *cn);
43 using Generator::generateProxyPage;
44 void generateProxyPage(Aggregate *aggregate);
45
46 void generateList(const Node *relative, const QString &selector);
47 void generateHeader(const QString &title, const QString &subtitle, const Node *node);
48 void closeTextSections();
49 void generateFooter();
50 void generateDocBookSynopsis(const Node *node);
51 void generateRequisites(const Aggregate *inner);
52 void generateQmlRequisites(const QmlTypeNode *qcn);
53 void generateSortedNames(const ClassNode *cn, const QList<RelatedClass> &rc);
54 void generateSortedQmlNames(const Node *base, const NodeList &subs);
55 bool generateStatus(const Node *node);
56 void generateGroupReferenceText(const Node *node);
57 bool generateThreadSafeness(const Node *node);
58 bool generateSince(const Node *node);
59 void generateAddendum(const Node *node, Generator::Addendum type, CodeMarker *marker,
60 bool generateNote) override;
61 using Generator::generateBody;
62 void generateBody(const Node *node);
63
64 bool generateText(const Text &text, const Node *relative) override;
65 const Atom *generateAtomList(const Atom *atom, const Node *relative, bool generate,
66 int &numAtoms);
67 qsizetype generateAtom(const Atom *atom, const Node *relative) override;
68
69private:
70
71 enum GeneratedListType { Auto, AutoSection, ItemizedList };
72
73 QXmlStreamWriter *startDocument(const Node *node);
74 QXmlStreamWriter *startDocument(const ExampleNode *en, const QString &file);
75 QXmlStreamWriter *startGenericDocument(const Node *node, const QString &fileName);
76 void endDocument();
77
78 void generateAnnotatedList(const Node *relative, const NodeList &nodeList,
79 const QString &selector, GeneratedListType type = Auto);
80 void generateAnnotatedLists(const Node *relative, const NodeMultiMap &nmm,
81 const QString &selector);
82 void generateCompactList(const Node *relative, const NodeMultiMap &nmm, bool includeAlphabet,
83 const QString &commonPrefix, const QString &selector);
84 using Generator::generateFileList;
85 void generateFileList(const ExampleNode *en, bool images);
86 void generateObsoleteMembers(const Sections &sections);
87 void generateObsoleteQmlMembers(const Sections &sections);
88 void generateSectionList(const Section &section, const Node *relative,
89 bool useObsoleteMembers = false);
90 void generateSectionInheritedList(const Section &section, const Node *relative);
91 void generateSynopsisName(const Node *node, const Node *relative, bool generateNameLink);
92 void generateParameter(const Parameter &parameter, const Node *relative, bool generateExtra,
93 bool generateType);
94 void generateSynopsis(const Node *node, const Node *relative, Section::Style style);
95 void generateEnumValue(const QString &enumValue, const Node *relative);
96 void generateDetailedMember(const Node *node, const PageNode *relative);
97 void generateDetailedQmlMember(Node *node, const Aggregate *relative);
98
99 void generateFullName(const Node *node, const Node *relative);
100 void generateFullName(const Node *apparentNode, const QString &fullName,
101 const Node *actualNode);
102 void generateBrief(const Node *node);
103 void generateAlsoList(const Node *node) override;
104 void generateSignatureList(const NodeList &nodes);
105 void generateReimplementsClause(const FunctionNode *fn);
106 void generateClassHierarchy(const Node *relative, NodeMultiMap &classMap);
107 void generateFunctionIndex(const Node *relative);
108 void generateLegaleseList(const Node *relative);
109 void generateExampleFilePage(const Node *en, ResolvedFile resolved_file, CodeMarker* = nullptr) override;
110 void generateOverloadedSignal(const Node *node);
111 void generateRequiredLinks(const Node *node);
112 void generateLinkToExample(const ExampleNode *en, const QString &baseUrl);
113
114 void typified(const QString &string, const Node *relative, bool trailingSpace = false,
115 bool generateType = true);
116 void generateLink(const Atom *atom);
117 void beginLink(const QString &link, const Node *node, const Node *relative);
118 void endLink();
119 void writeXmlId(const QString &id);
120 void writeXmlId(const Node *node);
121 inline void writeRawHtml(const QString &rawCode);
122 inline void newLine();
123 void startSectionBegin(const QString &id = "");
124 void startSectionBegin(const Node *node);
125 void startSectionEnd();
126 void startSection(const QString &id, const QString &title);
127 void startSection(const Node *node, const QString &title);
128 void startSection(const QString &title);
129 void endSection();
130 void writeAnchor(const QString &id);
131 void generateSimpleLink(const QString &href, const QString &text);
132 void generateStartRequisite(const QString &description);
133 void generateEndRequisite();
134 void generateRequisite(const QString &description, const QString &value);
135 void generateCMakeRequisite(const QStringList &values);
136 void generateSynopsisInfo(const QString &key, const QString &value);
137 void generateModifier(const QString &value);
138
139 // Generator state when outputting the documentation.
140 bool m_inListItemLineOpen { false };
141 int currentSectionLevel { 0 };
142 QStack<int> sectionLevels {};
143 QString m_qflagsHref {};
144 bool m_inTeletype { false };
145 bool m_hasSection { false };
146 bool m_closeSectionAfterGeneratedList { false };
147 bool m_closeSectionAfterRawTitle { false };
148 bool m_closeFigureWrapper { false };
149 bool m_tableHeaderAlreadyOutput { false };
150 bool m_closeTableRow { false };
151 bool m_closeTableCell { false };
152 std::pair<QString, QString> m_tableWidthAttr {};
153 bool m_inPara { false }; // Ignores nesting of paragraphs (like list items).
154 bool m_inBlockquote { false };
155 unsigned m_inList { 0 }; // Depth in number of nested lists.
156 bool m_rewritingCustomQmlModuleSummary { false };
157
158 // Generator configuration, set before starting the generation.
159 QString m_project {};
160 QString m_projectDescription {};
161 QString m_naturalLanguage {};
162 QString m_buildVersion {};
163 QXmlStreamWriter *m_writer { nullptr };
164 bool m_useDocBook52 { false }; // Enable tags from DocBook 5.2. Also called "extensions".
165 bool m_useITS { false }; // Enable ITS attributes for parts that should not be translated.
166
167 Config *m_config { nullptr };
168};
169
170QT_END_NAMESPACE
171
172#endif
173

source code of qttools/src/qdoc/qdoc/docbookgenerator.h