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 | |
16 | QT_BEGIN_NAMESPACE |
17 | |
18 | class Aggregate; |
19 | class ExampleNode; |
20 | class FunctionNode; |
21 | |
22 | class DocBookGenerator : public XmlGenerator |
23 | { |
24 | public: |
25 | explicit DocBookGenerator(FileResolver& file_resolver); |
26 | |
27 | void initializeGenerator() override; |
28 | QString format() override; |
29 | |
30 | protected: |
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 (const QString &title, const QString &subtitle, const Node *node); |
48 | void closeTextSections(); |
49 | void (); |
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 | |
69 | private: |
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 §ions); |
87 | void generateObsoleteQmlMembers(const Sections §ions); |
88 | void generateSectionList(const Section §ion, const Node *relative, |
89 | bool useObsoleteMembers = false); |
90 | void generateSectionInheritedList(const Section §ion, const Node *relative); |
91 | void generateSynopsisName(const Node *node, const Node *relative, bool generateNameLink); |
92 | void generateParameter(const Parameter ¶meter, const Node *relative, bool , |
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 { 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 | |
170 | QT_END_NAMESPACE |
171 | |
172 | #endif |
173 | |