From ac20c36608829b48db6dba82a9e34b62ba0e61b6 Mon Sep 17 00:00:00 2001 From: alandefreitas Date: Wed, 20 Nov 2024 17:25:29 -0300 Subject: [PATCH] docs(generators): common templates --- docs/modules/ROOT/pages/generators.adoc | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/docs/modules/ROOT/pages/generators.adoc b/docs/modules/ROOT/pages/generators.adoc index 6f11805bc..81aefb1ec 100644 --- a/docs/modules/ROOT/pages/generators.adoc +++ b/docs/modules/ROOT/pages/generators.adoc @@ -47,17 +47,23 @@ 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//layouts/single-symbol..hbs` directory. This template is a simple entry point that renders the partial relative to the symbol kind. +Each symbol goes through a main layout template in the `/generator//layouts/single-symbol..hbs` directory. This template is a simple entry point that renders the partial relative to the symbol kind. -The partials are located in the `share/mrdocs/addons/generator//partials` directory. It contains the following subdirectories: +The partials are located in the `/generator//partials` directory. It contains the following subdirectories: * `symbols`: Contains one partial for each symbol kind. The fields of each symbol object are described in the <> section. * `signature`: Contains one partial for each symbol kind that renders the signature of the symbol as if declared in {cpp}. * `types`: partials for rendering other types of objects in a canonical form. Please refer to the <> for more information on each type of object. +* `markup`: partials for rendering markup elements such as lists, tables, and code blocks, in the output format. + +Partials common to all generators are available in the `/generator/common/partials` directory. The common partials are loaded before the generator-specific partials, which can override any common partials. 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//partials` directory. +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 `/generator//partials` directory. 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.