docs: generator layout entry points

cppalliance · Nov 11, 2024 · e052cb7 · e052cb7
1 parent c6076e9
commit e052cb7
Show file tree

Hide file tree

Showing 11 changed files with 11 additions and 13 deletions.
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,2 +1,3 @@
		{{! The footer for single page documentation }}

		Created with MrDocs