forked from googleapis/google-cloud-cpp
-
Notifications
You must be signed in to change notification settings - Fork 0
/
doxygen2markdown.h
216 lines (172 loc) · 7.65 KB
/
doxygen2markdown.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
// Copyright 2023 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
#ifndef GOOGLE_CLOUD_CPP_DOCFX_DOXYGEN2MARKDOWN_H
#define GOOGLE_CLOUD_CPP_DOCFX_DOXYGEN2MARKDOWN_H
#include <pugixml.hpp>
#include <iosfwd>
#include <string>
#include <string_view>
#include <vector>
namespace docfx {
/**
* Keeps the state for markdown generation.
*
* As we recurse through the XML tree, we need to keep some information to
* generate valid Markdown text.
*/
struct MarkdownContext {
std::string paragraph_start = "\n\n";
std::string paragraph_indent;
std::string item_prefix;
std::vector<std::string> decorators;
bool skip_xrefsect = false;
};
/// Handles a sect4 node.
bool AppendIfSect4(std::ostream& os, MarkdownContext const& ctx,
pugi::xml_node node);
/// Handles a sect3 node.
bool AppendIfSect3(std::ostream& os, MarkdownContext const& ctx,
pugi::xml_node node);
/// Handles a sect2 node.
bool AppendIfSect2(std::ostream& os, MarkdownContext const& ctx,
pugi::xml_node node);
/// Handles a sect1 node.
bool AppendIfSect1(std::ostream& os, MarkdownContext const& ctx,
pugi::xml_node node);
/// Handles a `<xrefsect>` node.
bool AppendIfXRefSect(std::ostream& os, MarkdownContext const& ctx,
pugi::xml_node node);
/// Outputs a description node.
void AppendDescriptionType(std::ostream& os, MarkdownContext const& ctx,
pugi::xml_node node);
/// Handles a detailed description node.
bool AppendIfDetailedDescription(std::ostream& os, MarkdownContext const& ctx,
pugi::xml_node node);
/// Handles a brief description node.
bool AppendIfBriefDescription(std::ostream& os, MarkdownContext const& ctx,
pugi::xml_node node);
/**
* Handle plain text nodes.
*
* pugixml adds such nodes to represent the text between the markups. For
* example, something like:
*
* <foo>Some text<bar>more stuff</bar>hopefully the end</foo>
*
* Would have a node for "foo", which 3 children:
* 1. The first child is plain text, with value "Some text".
* 2. The second child has name "bar", and contains another child with
* one with value "more stuff".
* 3. Finally, the third child has value "hopefully the end", and it is also
* plain text.
*
* This is rather convenient when converting the XML nodes to the markdown
* representation.
*/
bool AppendIfPlainText(std::ostream& os, MarkdownContext const& ctx,
pugi::xml_node node);
/// Handles nodes with URL links.
bool AppendIfULink(std::ostream& os, MarkdownContext const& ctx,
pugi::xml_node node);
/// Handles nodes with **bold** text.
bool AppendIfBold(std::ostream& os, MarkdownContext const& ctx,
pugi::xml_node node);
/// Handles nodes with ~strike through~ text.
bool AppendIfStrike(std::ostream& os, MarkdownContext const& ctx,
pugi::xml_node node);
/// Handles *emphasis* in text.
bool AppendIfEmphasis(std::ostream& os, MarkdownContext const& ctx,
pugi::xml_node node);
/// Handles nodes with `computer output`.
bool AppendIfComputerOutput(std::ostream& os, MarkdownContext const& ctx,
pugi::xml_node node);
/// Handles `ref` nodes: all forms of links.
bool AppendIfRef(std::ostream& os, MarkdownContext const& ctx,
pugi::xml_node node);
/// Handles `ndash` elements.
bool AppendIfNDash(std::ostream& os, MarkdownContext const& ctx,
pugi::xml_node node);
/// Part of the implementation of AppendIfParagraph().
bool AppendIfDocTitleCmdGroup(std::ostream& os, MarkdownContext const& ctx,
pugi::xml_node node);
/// Part of the implementation of AppendIfParagraph().
bool AppendIfDocCmdGroup(std::ostream& os, MarkdownContext const& ctx,
pugi::xml_node node);
/// Handle full paragraphs.
bool AppendIfParagraph(std::ostream& os, MarkdownContext const& ctx,
pugi::xml_node node);
/// Handle `programlisting` elements.
bool AppendIfProgramListing(std::ostream& os, MarkdownContext const& ctx,
pugi::xml_node node);
/// Handle `verbatim` elements.
bool AppendIfVerbatim(std::ostream& os, MarkdownContext const& ctx,
pugi::xml_node node);
/// Handle `<parblock>` elements.
bool AppendIfParBlock(std::ostream& os, MarkdownContext const& ctx,
pugi::xml_node node);
/// Handle `<table>` elements.
bool AppendIfTable(std::ostream& os, MarkdownContext const& ctx,
pugi::xml_node node);
/// Handle `<row>` elements in a `<table>`.
bool AppendIfTableRow(std::ostream& os, MarkdownContext const& ctx,
pugi::xml_node node);
/// Handle `<entry>` elements in a `<table>`.
bool AppendIfTableEntry(std::ostream& os, MarkdownContext const& ctx,
pugi::xml_node node);
/// Handle `codeline` elements.
bool AppendIfCodeline(std::ostream& os, MarkdownContext const& ctx,
pugi::xml_node node);
/// Handle `highlight` elements.
bool AppendIfHighlight(std::ostream& os, MarkdownContext const& ctx,
pugi::xml_node node);
/// Handle `sp` elements embedded in `highlight` elements.
bool AppendIfHighlightSp(std::ostream& os, MarkdownContext const& ctx,
pugi::xml_node node);
/// Handle `ref` elements embedded in `highlight` elements.
bool AppendIfHighlightRef(std::ostream& os, MarkdownContext const& ctx,
pugi::xml_node node);
/// Handle itemized lists.
bool AppendIfItemizedList(std::ostream& os, MarkdownContext const& ctx,
pugi::xml_node node);
/// Handle `orderedlist` elements.
bool AppendIfOrderedList(std::ostream& os, MarkdownContext const& ctx,
pugi::xml_node node);
/// Handle a single list item.
bool AppendIfListItem(std::ostream& os, MarkdownContext const& ctx,
pugi::xml_node node);
/**
* Handle `variablelist` elements.
*
* Most commonly used in lists of deprecated symbols, these are pairs of
* terms (a linked code entity), and a sequence of text.
*/
bool AppendIfVariableList(std::ostream& os, MarkdownContext const& ctx,
pugi::xml_node node);
/// Handle a single `varlistentry` element.
bool AppendIfVariableListEntry(std::ostream& os, MarkdownContext const& ctx,
pugi::xml_node node);
/// Handle a single `listitem` in a variable list.
bool AppendIfVariableListItem(std::ostream& os, MarkdownContext const& ctx,
pugi::xml_node node);
/// Handle a `simplesect` element (a section without sub-sections).
bool AppendIfSimpleSect(std::ostream& os, MarkdownContext const& ctx,
pugi::xml_node node);
/// Handle an `anchor` element.
bool AppendIfAnchor(std::ostream& os, MarkdownContext const& ctx,
pugi::xml_node node);
/// Handle the title for a section-like element.
void AppendTitle(std::ostream& os, MarkdownContext const& ctx,
pugi::xml_node node);
} // namespace docfx
#endif // GOOGLE_CLOUD_CPP_DOCFX_DOXYGEN2MARKDOWN_H