docs: generator layout entry points

alandefreitas · alandefreitas · commit e052cb7cfbe6 · 2024-11-11T12:22:34.000-03:00
diff --git a/docs/modules/ROOT/pages/generators.adoc b/docs/modules/ROOT/pages/generators.adoc
@@ -47,7 +47,9 @@ The templates used to generate the documentation are located in the `share/mrdoc
 addons: /path/to/custom/addons
 ----
 
-Each symbol goes through a main layout template in the `share/mrdocs/addons/generator/<generator>/layouts` directory. The multipage generator renders the layout as separate pages for each symbol. The single-page generator renders and concatenates the layout.
+Each symbol goes through a main layout template in the `share/mrdocs/addons/generator/<generator>/layouts/single-symbol.<generator>.hbs` directory.
+
+The multipage generator renders the layout multiple times as separate pages for each symbol. The single-page generator renders the layout multiple times and concatenates the results in a single page.
 
 Each time the generator encounters a symbol, it renders the layout template with the symbol data as the Handlebars context. The layout template can include other partial templates to render the symbol data. These partials are available in the `share/mrdocs/addons/generator/<generator>/partials` directory.
 
diff --git a/share/mrdocs/addons/generator/asciidoc/layouts/overload-set.adoc.hbs b/share/mrdocs/addons/generator/asciidoc/layouts/overload-set.adoc.hbs
@@ -1,3 +1,4 @@
+{{! A page when the symbol type is "overloads" }}
 {{#if relfileprefix}}:relfileprefix: {{relfileprefix}}{{/if}}
 [#{{sectionref}}]
 
diff --git a/share/mrdocs/addons/generator/asciidoc/layouts/page.adoc.hbs b/share/mrdocs/addons/generator/asciidoc/layouts/page.adoc.hbs
diff --git a/share/mrdocs/addons/generator/asciidoc/layouts/single-footer.adoc.hbs b/share/mrdocs/addons/generator/asciidoc/layouts/single-footer.adoc.hbs
@@ -1,2 +1,3 @@
+{{! The footer for single page documentation }}
 
 Created with MrDocs
diff --git a/share/mrdocs/addons/generator/asciidoc/layouts/single-header.adoc.hbs b/share/mrdocs/addons/generator/asciidoc/layouts/single-header.adoc.hbs
@@ -1,2 +1,3 @@
+{{! The header for single page documentation }}
 = Reference
 :mrdocs:
diff --git a/share/mrdocs/addons/generator/asciidoc/layouts/single-symbol.adoc.hbs b/share/mrdocs/addons/generator/asciidoc/layouts/single-symbol.adoc.hbs
@@ -1,3 +1,4 @@
+{{! The section with a symbol in single page output or the symbol page in multi page output }}
 {{#if relfileprefix}}:relfileprefix: {{relfileprefix}}{{/if}}
 [#{{sectionref}}]
 
diff --git a/share/mrdocs/addons/generator/html/layouts/overload-set.html.hbs b/share/mrdocs/addons/generator/html/layouts/overload-set.html.hbs
@@ -1,3 +1,4 @@
+{{! A page when the symbol type is "overloads" }}
 {{#if relfileprefix}}<meta name="relfileprefix" content="{{relfileprefix}}">{{/if}}
 <div id="{{#if (is_multipage)}}{{symbol.id}}{{else}}{{symbol.ref}}{{/if}}">
 
diff --git a/share/mrdocs/addons/generator/html/layouts/page.html.hbs b/share/mrdocs/addons/generator/html/layouts/page.html.hbs
diff --git a/share/mrdocs/addons/generator/html/layouts/single-footer.html.hbs b/share/mrdocs/addons/generator/html/layouts/single-footer.html.hbs
@@ -1,3 +1,4 @@
+{{! The footer for single page documentation }}
         </div>
         <div><h4>Created with MrDocs</h4></div>
     </body>
diff --git a/share/mrdocs/addons/generator/html/layouts/single-header.html.hbs b/share/mrdocs/addons/generator/html/layouts/single-header.html.hbs
@@ -1,3 +1,4 @@
+{{! The header for single page documentation }}
 </html>
     <head></head>
     <body>
diff --git a/share/mrdocs/addons/generator/html/layouts/single-symbol.html.hbs b/share/mrdocs/addons/generator/html/layouts/single-symbol.html.hbs
@@ -1,3 +1,4 @@
+{{! The section with a symbol in single page output or the symbol page in multi page output }}
 {{#if relfileprefix}}:relfileprefix: {{relfileprefix}}{{/if}}
 [#{{#if (is_multipage)}}{{symbol.id}}{{else}}{{symbol.ref}}{{/if}}]
 

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+{{! A page when the symbol type is "overloads" }}`
`1`	`2`	`{{#if relfileprefix}}:relfileprefix: {{relfileprefix}}{{/if}}`
`2`	`3`	`[#{{sectionref}}]`
`3`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,2 +1,3 @@`
	`1`	`+{{! The footer for single page documentation }}`
`1`	`2`
`2`	`3`	`Created with MrDocs`
Original file line number	Diff line number	Diff line change
`@@ -1,2 +1,3 @@`
	`1`	`+{{! The header for single page documentation }}`
`1`	`2`	`= Reference`
`2`	`3`	`:mrdocs:`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+{{! The section with a symbol in single page output or the symbol page in multi page output }}`
`1`	`2`	`{{#if relfileprefix}}:relfileprefix: {{relfileprefix}}{{/if}}`
`2`	`3`	`[#{{sectionref}}]`
`3`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+{{! A page when the symbol type is "overloads" }}`
`1`	`2`	`{{#if relfileprefix}}<meta name="relfileprefix" content="{{relfileprefix}}">{{/if}}`
`2`	`3`	`<div id="{{#if (is_multipage)}}{{symbol.id}}{{else}}{{symbol.ref}}{{/if}}">`
`3`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+{{! The footer for single page documentation }}`
`1`	`2`	`</div>`
`2`	`3`	`<div><h4>Created with MrDocs</h4></div>`
`3`	`4`	`</body>`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+{{! The header for single page documentation }}`
`1`	`2`	`</html>`
`2`	`3`	`<head></head>`
`3`	`4`	`<body>`