Skip to content

Commit 36a9eb8

Browse files
alandefreitasalandefreitas
committed
fix: multipage section levels
1 parent c194416 commit 36a9eb8

File tree

97 files changed

+1926
-1784
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

97 files changed

+1926
-1784
lines changed

‎docs/modules/ROOT/pages/generators.adoc

+1-1
Original file line numberDiff line numberDiff line change
@@ -107,7 +107,7 @@ The multipage generator renders the layout multiple times as separate pages for
107107
The single-page generator renders the layout multiple times and concatenates the results in a single page.
108108

109109
Each time the generator encounters a symbol, it renders the layout template with the symbol data as the Handlebars context.
110-
The layout template can include other partial templates to render the symbol data.These partials are available in the `<addons>/generator/<generator>/partials` directory.
110+
The layout template can include other partial templates to render the symbol data. These partials are available in the `<addons>/generator/<generator>/partials` directory.
111111

112112
The Document Object Model (DOM) for each symbol includes all information about the symbol.One advantage of custom templates over post-processing XML files is the ability to access symbols as a graph.If symbol `A` refers to symbol `B`, some properties of symbol `B` are likely to be required in the documentation of `A`.All templates and generators can access a reference to `B` by searching the symbol tree or simply by accessing the elements `A` refers to.All references to other symbols are resolved in the templates.
113113

‎include/mrdocs/Support/Handlebars.hpp

+11
Original file line numberDiff line numberDiff line change
@@ -1164,6 +1164,17 @@ MRDOCS_DECL
11641164
void
11651165
registerLogicalHelpers(Handlebars& hbs);
11661166

1167+
/** Register math helpers into a Handlebars instance
1168+
1169+
This function registers a number of common helpers that perform
1170+
mathemathical operations.
1171+
1172+
@param hbs The Handlebars instance to register the helpers into
1173+
*/
1174+
MRDOCS_DECL
1175+
void
1176+
registerMathHelpers(Handlebars& hbs);
1177+
11671178
/** Register string helpers into a Handlebars instance
11681179
11691180
This function registers a number of common helpers that operate on

‎share/mrdocs/addons/generator/adoc/partials/markup/h.adoc.hbs

+2
Original file line numberDiff line numberDiff line change
@@ -1 +1,3 @@
1+
{{#if id}}[#{{{id}}}]
2+
{{/if}}
13
={{select level (repeat "=" level) (select @root.config.multipage "==" "=")}} {{> @partial-block }}

‎share/mrdocs/addons/generator/adoc/partials/symbol.adoc.hbs

+28-16
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,20 @@
1+
{{!--
2+
Renders the documentation for a symbol in a format that is coherent for all symbol kinds.
3+
4+
This partial conditionally checks if each documentation section exists and if a symbol kind
5+
does not provide a specific kind of documentation section, that section is not rendered.
6+
7+
Expected Context: {Root Context Object}
8+
9+
Example:
10+
{{> symbol }}
11+
12+
See: https://mrdocs.com/docs/mrdocs/develop/generators.html#dom_reference
13+
--}}
114
{{#unless @root.config.multipage }}
215
{{! Single page documentation: symbol is not available to the wrapper but it's available here }}
316
{{! Include the symbol title at a higher level }}
4-
[#{{{symbol.anchor}}}]
5-
== {{> symbol/qualified-name symbol }}
17+
{{#> markup/h level=1 id=symbol.anchor }}{{> symbol/qualified-name symbol }}{{/markup/h}}
618
{{/unless}}
719

820
{{! Brief }}
@@ -12,7 +24,7 @@
1224
{{/if}}
1325
{{! Synopsis }}
1426
{{#unless (contains (arr "namespace") symbol.kind)}}
15-
=={{#unless @root.config.multipage}}={{/unless}} Synopsis
27+
{{#> markup/dynamic-level-h }}Synopsis{{/markup/dynamic-level-h}}
1628

1729
{{>location/source dcl=(primary_location symbol)}}
1830

@@ -52,7 +64,7 @@
5264
{{else if symbol.members}}
5365
{{! Members }}
5466
{{#if (and symbol.members (ne symbol.kind "overloads"))}}
55-
=={{#unless @root.config.multipage}}={{/unless}} Members
67+
{{#> markup/dynamic-level-h }}Members{{/markup/dynamic-level-h}}
5668
5769
[,cols=2]
5870
|===
@@ -71,14 +83,14 @@
7183
{{/if}}
7284
{{! Description }}
7385
{{#if symbol.doc.description}}
74-
=={{#unless @root.config.multipage}}={{/unless}} Description
86+
{{#> markup/dynamic-level-h }}Description{{/markup/dynamic-level-h}}
7587
7688
{{symbol.doc.description}}
7789
7890
{{/if}}
7991
{{! Using symbols }}
8092
{{#if symbol.shadows}}
81-
=={{#unless @root.config.multipage}}={{/unless}} Introduced Symbols
93+
{{#> markup/dynamic-level-h }}Introduced Symbols{{/markup/dynamic-level-h}}
8294
8395
|===
8496
| Name
@@ -91,7 +103,7 @@
91103
{{! Exceptions }}
92104
{{#if (ne symbol.kind "overloads")}}
93105
{{#if symbol.doc.exceptions}}
94-
=={{#unless @root.config.multipage}}={{/unless}} Exceptions
106+
{{#> markup/dynamic-level-h }}Exceptions{{/markup/dynamic-level-h}}
95107
96108
|===
97109
| Name | Thrown on
@@ -106,7 +118,7 @@
106118
{{else}}
107119
{{#with (flattenUnique symbol.members "doc.exceptions" "exception") as |allExceptions|}}
108120
{{#if (ne (len allExceptions) 0)}}
109-
=={{#unless @root.config.multipage}}={{/unless}} Exceptions
121+
{{#> markup/dynamic-level-h }}Exceptions{{/markup/dynamic-level-h}}
110122
111123
|===
112124
| Name | Thrown on
@@ -122,15 +134,15 @@
122134
{{/if}}
123135
{{! Return value }}
124136
{{#if symbol.doc.returns}}
125-
=={{#unless @root.config.multipage}}={{/unless}} Return Value
137+
{{#> markup/dynamic-level-h }}Return Value{{/markup/dynamic-level-h}}
126138
127139
{{{symbol.doc.returns}}}
128140
129141
{{/if}}
130142
{{! Template Parameters }}
131143
{{#if (ne symbol.kind "overloads")}}
132144
{{#if symbol.doc.tparams}}
133-
=={{#unless @root.config.multipage}}={{/unless}} Template Parameters
145+
{{#> markup/dynamic-level-h }}Template Parameters{{/markup/dynamic-level-h}}
134146
135147
|===
136148
| Name | Description
@@ -145,7 +157,7 @@
145157
{{else}}
146158
{{#with (flattenUnique symbol.members "doc.tparams" "name") as |allTParams|}}
147159
{{#if (ne (len allTParams) 0)}}
148-
=={{#unless @root.config.multipage}}={{/unless}} Parameters
160+
{{#> markup/dynamic-level-h }}Parameters{{/markup/dynamic-level-h}}
149161
150162
|===
151163
| Name | Description
@@ -162,7 +174,7 @@
162174
{{! Parameters }}
163175
{{#if (ne symbol.kind "overloads")}}
164176
{{#if symbol.doc.params}}
165-
=={{#unless @root.config.multipage}}={{/unless}} Parameters
177+
{{#> markup/dynamic-level-h }}Parameters{{/markup/dynamic-level-h}}
166178
167179
|===
168180
| Name | Description
@@ -177,7 +189,7 @@
177189
{{else}}
178190
{{#with (flattenUnique symbol.members "doc.params" "name") as |allParams|}}
179191
{{#if (ne (len allParams) 0)}}
180-
=={{#unless @root.config.multipage}}={{/unless}} Parameters
192+
{{#> markup/dynamic-level-h }}Parameters{{/markup/dynamic-level-h}}
181193
182194
|===
183195
| Name | Description
@@ -193,7 +205,7 @@
193205
{{/if}}
194206
{{! Preconditions }}
195207
{{#if symbol.doc.preconditions}}
196-
=={{#unless @root.config.multipage}}={{/unless}} Preconditions
208+
{{#> markup/dynamic-level-h }}Preconditions{{/markup/dynamic-level-h}}
197209
198210
{{#each symbol.doc.preconditions}}
199211
{{{.}}}
@@ -202,7 +214,7 @@
202214
{{/if}}
203215
{{! Postconditions }}
204216
{{#if symbol.doc.postconditions}}
205-
=={{#unless @root.config.multipage}}={{/unless}} Postconditions
217+
{{#> markup/dynamic-level-h }}Postconditions{{/markup/dynamic-level-h}}
206218
207219
{{#each symbol.doc.postconditions}}
208220
{{{.}}}
@@ -211,7 +223,7 @@
211223
{{/if}}
212224
{{! See Also }}
213225
{{#if symbol.doc.see}}
214-
=={{#unless @root.config.multipage}}={{/unless}} See Also
226+
{{#> markup/dynamic-level-h }}See Also{{/markup/dynamic-level-h}}
215227
216228
{{#each symbol.doc.see}}
217229
{{{.}}}

‎share/mrdocs/addons/generator/common/partials/markup/dynamic-level-h.hbs

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
{{#> markup/h
2+
level=(select @root.config.multipage (or level 1) (add (or level 1) 1))
3+
id=id
4+
}}
5+
{{> @partial-block }}
6+
{{/markup/h}}

‎share/mrdocs/addons/generator/html/partials/markup/h.html.hbs

+1-1
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
<h{{or level 3}}{{#if class}} class="{{class}}"{{/if}}>{{> @partial-block }}</h{{or level 3}}>
1+
<h{{or level 3}}{{#if class}} class="{{{class}}}"{{/if}}{{#if id}} id="{{{id}}}"{{/if}}>{{> @partial-block }}</h{{or level 3}}>

‎share/mrdocs/addons/generator/html/partials/symbol.html.hbs

+29-16
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,22 @@
1+
{{!--
2+
Renders the documentation for a symbol in a format that is coherent for all symbol kinds.
3+
4+
This partial conditionally checks if each documentation section exists and if a symbol kind
5+
does not provide a specific kind of documentation section, that section is not rendered.
6+
7+
Expected Context: {Root Context Object}
8+
9+
Example:
10+
{{> symbol }}
11+
12+
See: https://mrdocs.com/docs/mrdocs/develop/generators.html#dom_reference
13+
--}}
114
{{#unless @root.config.multipage }}
215
{{! Single page documentation: symbol is not available to the wrapper but it's available here }}
316
{{! Include the symbol title at a higher level }}
4-
<div id="{{{symbol.anchor}}}">
517
<div>
6-
<h2>{{> symbol/qualified-name symbol }}</h2>
18+
<div>
19+
{{#> markup/h level=2 id=symbol.anchor }}{{> symbol/qualified-name symbol }}{{/markup/h}}
720
{{/unless}}
821
{{! Brief }}
922
{{#if symbol.doc.brief}}
@@ -18,7 +31,7 @@
1831
{{! Synopsis }}
1932
{{#unless (contains (arr "namespace") symbol.kind)}}
2033
<div>
21-
<h3>Synopsis</h3>
34+
{{#> markup/dynamic-level-h level=2 }}Synopsis{{/markup/dynamic-level-h}}
2235
<div>
2336
{{>location/source dcl=(primary_location symbol)}}
2437
</div>
@@ -59,7 +72,7 @@
5972
{{! Members }}
6073
{{#if (and symbol.members (ne symbol.kind "overloads"))}}
6174
<div>
62-
<h3>Members</h3>
75+
{{#> markup/dynamic-level-h level=2 }}Members{{/markup/dynamic-level-h}}
6376
<table>
6477
<thead>
6578
<tr>
@@ -90,15 +103,15 @@
90103
{{! Description }}
91104
{{#if symbol.doc.description}}
92105
<div>
93-
<h3>Description</h3>
106+
{{#> markup/dynamic-level-h level=2 }}Description{{/markup/dynamic-level-h}}
94107
{{{symbol.doc.description}}}
95108

96109
</div>
97110
{{/if}}
98111
{{! Using symbols }}
99112
{{#if symbol.shadows}}
100113
<div>
101-
<h3>Introduced Symbols</h3>
114+
{{#> markup/dynamic-level-h level=2 }}Introduced Symbols{{/markup/dynamic-level-h}}
102115
<table>
103116
<thead>
104117
<tr>
@@ -120,7 +133,7 @@
120133
{{#if (ne symbol.kind "overloads")}}
121134
{{#if symbol.doc.exceptions}}
122135
<div>
123-
<h3>Exceptions</h3>
136+
{{#> markup/dynamic-level-h level=2 }}Exceptions{{/markup/dynamic-level-h}}
124137
<table>
125138
<thead>
126139
<tr>
@@ -143,7 +156,7 @@
143156
{{#with (flattenUnique symbol.members "doc.exceptions" "exception") as |allExceptions|}}
144157
{{#if (ne (len allExceptions) 0)}}
145158
<div>
146-
<h3>Exceptions</h3>
159+
{{#> markup/dynamic-level-h level=2 }}Exceptions{{/markup/dynamic-level-h}}
147160
<table>
148161
<thead>
149162
<tr>
@@ -167,15 +180,15 @@
167180
{{! Return value }}
168181
{{#if symbol.doc.returns}}
169182
<div>
170-
<h3>Return Value</h3>
183+
{{#> markup/dynamic-level-h level=2 }}Return Value{{/markup/dynamic-level-h}}
171184
{{{symbol.doc.returns}}}
172185
</div>
173186
{{/if}}
174187
{{! Template Parameters }}
175188
{{#if (ne symbol.kind "overloads")}}
176189
{{#if symbol.doc.tparams}}
177190
<div>
178-
<h3>Template Parameters</h3>
191+
{{#> markup/dynamic-level-h level=2 }}Template Parameters{{/markup/dynamic-level-h}}
179192
<table>
180193
<thead>
181194
<tr>
@@ -198,7 +211,7 @@
198211
{{#with (flattenUnique symbol.members "doc.tparams" "name") as |allTParams|}}
199212
{{#if (ne (len allTParams) 0)}}
200213
<div>
201-
<h3>Template Parameters</h3>
214+
{{#> markup/dynamic-level-h level=2 }}Template Parameters{{/markup/dynamic-level-h}}
202215
<table>
203216
<thead>
204217
<tr>
@@ -223,7 +236,7 @@
223236
{{#if (ne symbol.kind "overloads")}}
224237
{{#if symbol.doc.params}}
225238
<div>
226-
<h3>Parameters</h3>
239+
{{#> markup/dynamic-level-h level=2 }}Parameters{{/markup/dynamic-level-h}}
227240
<table>
228241
<thead>
229242
<tr>
@@ -246,7 +259,7 @@
246259
{{#with (flattenUnique symbol.members "doc.params" "name") as |allParams|}}
247260
{{#if (ne (len allParams) 0)}}
248261
<div>
249-
<h3>Parameters</h3>
262+
{{#> markup/dynamic-level-h level=2 }}Parameters{{/markup/dynamic-level-h}}
250263
<table>
251264
<thead>
252265
<tr>
@@ -270,7 +283,7 @@
270283
{{! Preconditions }}
271284
{{#if symbol.doc.preconditions}}
272285
<div>
273-
<h3>Preconditions</h3>
286+
{{#> markup/dynamic-level-h level=2 }}Preconditions{{/markup/dynamic-level-h}}
274287
{{#each symbol.doc.preconditions}}
275288
<p>{{.}}</p>
276289
{{/each}}
@@ -279,7 +292,7 @@
279292
{{! Postconditions }}
280293
{{#if symbol.doc.postconditions}}
281294
<div>
282-
<h3>Postconditions</h3>
295+
{{#> markup/dynamic-level-h level=2 }}Postconditions{{/markup/dynamic-level-h}}
283296
{{#each symbol.doc.postconditions}}
284297
<p>{{.}}</p>
285298
{{/each}}
@@ -288,7 +301,7 @@
288301
{{! See Also }}
289302
{{#if symbol.doc.see}}
290303
<div>
291-
<h3>See Also</h3>
304+
{{#> markup/dynamic-level-h level=2 }}See Also{{/markup/dynamic-level-h}}
292305
{{#each symbol.doc.see}}
293306
<p>{{.}}</p>
294307
{{/each}}

‎src/lib/Gen/hbs/Builder.cpp

+1
Original file line numberDiff line numberDiff line change
@@ -233,6 +233,7 @@ Builder(
233233
helpers::registerStringHelpers(hbs_);
234234
helpers::registerAntoraHelpers(hbs_);
235235
helpers::registerLogicalHelpers(hbs_);
236+
helpers::registerMathHelpers(hbs_);
236237
helpers::registerContainerHelpers(hbs_);
237238
hbs_.registerHelper("relativize", dom::makeInvocable(relativize_fn));
238239

0 commit comments

Comments
 (0)