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 Qt::SortOrder sortOrder = Qt::AscendingOrder);
48 void generateHeader(const QString &title, const QString &subtitle, const Node *node);
49 void closeTextSections();
50 void generateFooter();
51 void generateDocBookSynopsis(const Node *node);
52 void generateRequisites(const Aggregate *inner);
53 void generateQmlRequisites(const QmlTypeNode *qcn);
54 void generateSortedNames(const ClassNode *cn, const QList<RelatedClass> &rc);
55 void generateSortedQmlNames(const Node *base, const QStringList &knownTypes,
56 const NodeList &subs);
57 bool generateStatus(const Node *node);
58 void generateGroupReferenceText(const Node *node);
59 bool generateThreadSafeness(const Node *node);
60 bool generateSince(const Node *node);
61 void generateAddendum(const Node *node, Generator::Addendum type, CodeMarker *marker,
62 AdmonitionPrefix prefix) override;
63 using Generator::generateBody;
64 void generateBody(const Node *node);
65
66 bool generateText(const Text &text, const Node *relative) override;
67 qsizetype generateAtom(const Atom *atom, const Node *relative, CodeMarker*) 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 Qt::SortOrder sortOrder = Qt::AscendingOrder);
81 void generateAnnotatedLists(const Node *relative, const NodeMultiMap &nmm,
82 const QString &selector);
83 void generateCompactList(const Node *relative, const NodeMultiMap &nmm, bool includeAlphabet,
84 const QString &commonPrefix, const QString &selector);
85 using Generator::generateFileList;
86 void generateFileList(const ExampleNode *en, bool images);
87 void generateObsoleteMembers(const Sections &sections);
88 void generateObsoleteQmlMembers(const Sections &sections);
89 void generateSectionList(const Section &section, const Node *relative,
90 bool useObsoleteMembers = false);
91 void generateSectionInheritedList(const Section &section, const Node *relative);
92 void generateSynopsisName(const Node *node, const Node *relative, bool generateNameLink);
93 void generateParameter(const Parameter &parameter, const Node *relative, bool generateExtra,
94 bool generateType);
95 void generateSynopsis(const Node *node, const Node *relative, Section::Style style);
96 void generateEnumValue(const QString &enumValue, const Node *relative);
97 void generateDetailedMember(const Node *node, const PageNode *relative);
98 void generateDetailedQmlMember(Node *node, const Aggregate *relative);
99
100 void generateFullName(const Node *node, const Node *relative);
101 void generateFullName(const Node *apparentNode, const QString &fullName,
102 const Node *actualNode);
103 void generateBrief(const Node *node);
104 void generateAlsoList(const Node *node) override;
105 void generateSignatureList(const NodeList &nodes);
106 void generateReimplementsClause(const FunctionNode *fn);
107 void generateClassHierarchy(const Node *relative, NodeMultiMap &classMap);
108 void generateFunctionIndex(const Node *relative);
109 void generateLegaleseList(const Node *relative);
110 void generateExampleFilePage(const Node *en, ResolvedFile resolved_file, CodeMarker* = nullptr) override;
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 newLine();
122 void startSectionBegin(const QString &id = "");
123 void startSectionBegin(const Node *node);
124 void startSectionEnd();
125 void startSection(const QString &id, const QString &title);
126 void startSection(const Node *node, const QString &title);
127 void startSection(const QString &title);
128 void endSection();
129 void writeAnchor(const QString &id);
130 void generateSimpleLink(const QString &href, const QString &text);
131 void generateStartRequisite(const QString &description);
132 void generateEndRequisite();
133 void generateRequisite(const QString &description, const QString &value);
134 void generateCMakeRequisite(const QString &findPackage, const QString &linkLibraries);
135 void generateSynopsisInfo(const QString &key, const QString &value);
136 void generateModifier(const QString &value);
137
138 // Generator state when outputting the documentation.
139 bool m_inListItemLineOpen { false };
140 int currentSectionLevel { 0 };
141 QStack<int> sectionLevels {};
142 QString m_qflagsHref {};
143 bool m_inTeletype { false };
144 bool m_hasSection { false };
145 bool m_closeSectionAfterGeneratedList { false };
146 bool m_closeSectionAfterRawTitle { false };
147 bool m_closeFigureWrapper { false };
148 bool m_tableHeaderAlreadyOutput { false };
149 bool m_closeTableRow { false };
150 bool m_closeTableCell { false };
151 std::pair<QString, QString> m_tableWidthAttr {};
152 bool m_inPara { false }; // Ignores nesting of paragraphs (like list items).
153 bool m_inBlockquote { false };
154 unsigned m_inList { 0 }; // Depth in number of nested lists.
155
156 // Generator configuration, set before starting the generation.
157 QString m_project {};
158 QString m_productName {};
159 QString m_projectDescription {};
160 QString m_naturalLanguage {};
161 QString m_buildVersion {};
162 QXmlStreamWriter *m_writer { nullptr };
163 bool m_useDocBook52 { false }; // Enable tags from DocBook 5.2. Also called "extensions".
164 bool m_useITS { false }; // Enable ITS attributes for parts that should not be translated.
165
166 Config *m_config { nullptr };
167};
168
169QT_END_NAMESPACE
170
171#endif
172

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