Skip to content

fix: multipage section levels #750

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Dec 2, 2024
Merged

fix: multipage section levels #750

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/modules/ROOT/pages/generators.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -107,7 +107,7 @@ The multipage generator renders the layout multiple times as separate pages for
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 `<addons>/generator/<generator>/partials` directory.
The layout template can include other partial templates to render the symbol data. These partials are available in the `<addons>/generator/<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.

Expand Down
11 changes: 11 additions & 0 deletions include/mrdocs/Support/Handlebars.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1164,6 +1164,17 @@ MRDOCS_DECL
void
registerLogicalHelpers(Handlebars& hbs);

/** Register math helpers into a Handlebars instance

This function registers a number of common helpers that perform
mathemathical operations.

@param hbs The Handlebars instance to register the helpers into
*/
MRDOCS_DECL
void
registerMathHelpers(Handlebars& hbs);

/** Register string helpers into a Handlebars instance

This function registers a number of common helpers that operate on
Expand Down
2 changes: 2 additions & 0 deletions share/mrdocs/addons/generator/adoc/partials/markup/h.adoc.hbs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1 +1,3 @@
{{#if id}}[#{{{id}}}]
{{/if}}
={{select level (repeat "=" level) (select @root.config.multipage "==" "=")}} {{> @partial-block }}
44 changes: 28 additions & 16 deletions share/mrdocs/addons/generator/adoc/partials/symbol.adoc.hbs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,20 @@
{{!--
Renders the documentation for a symbol in a format that is coherent for all symbol kinds.

This partial conditionally checks if each documentation section exists and if a symbol kind
does not provide a specific kind of documentation section, that section is not rendered.

Expected Context: {Root Context Object}

Example:
{{> symbol }}

See: https://mrdocs.com/docs/mrdocs/develop/generators.html#dom_reference
--}}
{{#unless @root.config.multipage }}
{{! Single page documentation: symbol is not available to the wrapper but it's available here }}
{{! Include the symbol title at a higher level }}
[#{{{symbol.anchor}}}]
== {{> symbol/qualified-name symbol }}
{{#> markup/h level=1 id=symbol.anchor }}{{> symbol/qualified-name symbol }}{{/markup/h}}
{{/unless}}

{{! Brief }}
Expand All @@ -12,7 +24,7 @@
{{/if}}
{{! Synopsis }}
{{#unless (contains (arr "namespace") symbol.kind)}}
=={{#unless @root.config.multipage}}={{/unless}} Synopsis
{{#> markup/dynamic-level-h }}Synopsis{{/markup/dynamic-level-h}}

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

Expand Down Expand Up @@ -52,7 +64,7 @@
{{else if symbol.members}}
{{! Members }}
{{#if (and symbol.members (ne symbol.kind "overloads"))}}
=={{#unless @root.config.multipage}}={{/unless}} Members
{{#> markup/dynamic-level-h }}Members{{/markup/dynamic-level-h}}

[,cols=2]
|===
Expand All @@ -71,14 +83,14 @@
{{/if}}
{{! Description }}
{{#if symbol.doc.description}}
=={{#unless @root.config.multipage}}={{/unless}} Description
{{#> markup/dynamic-level-h }}Description{{/markup/dynamic-level-h}}

{{symbol.doc.description}}

{{/if}}
{{! Using symbols }}
{{#if symbol.shadows}}
=={{#unless @root.config.multipage}}={{/unless}} Introduced Symbols
{{#> markup/dynamic-level-h }}Introduced Symbols{{/markup/dynamic-level-h}}

|===
| Name
Expand All @@ -91,7 +103,7 @@
{{! Exceptions }}
{{#if (ne symbol.kind "overloads")}}
{{#if symbol.doc.exceptions}}
=={{#unless @root.config.multipage}}={{/unless}} Exceptions
{{#> markup/dynamic-level-h }}Exceptions{{/markup/dynamic-level-h}}

|===
| Name | Thrown on
Expand All @@ -106,7 +118,7 @@
{{else}}
{{#with (flattenUnique symbol.members "doc.exceptions" "exception") as |allExceptions|}}
{{#if (ne (len allExceptions) 0)}}
=={{#unless @root.config.multipage}}={{/unless}} Exceptions
{{#> markup/dynamic-level-h }}Exceptions{{/markup/dynamic-level-h}}

|===
| Name | Thrown on
Expand All @@ -122,15 +134,15 @@
{{/if}}
{{! Return value }}
{{#if symbol.doc.returns}}
=={{#unless @root.config.multipage}}={{/unless}} Return Value
{{#> markup/dynamic-level-h }}Return Value{{/markup/dynamic-level-h}}

{{{symbol.doc.returns}}}

{{/if}}
{{! Template Parameters }}
{{#if (ne symbol.kind "overloads")}}
{{#if symbol.doc.tparams}}
=={{#unless @root.config.multipage}}={{/unless}} Template Parameters
{{#> markup/dynamic-level-h }}Template Parameters{{/markup/dynamic-level-h}}

|===
| Name | Description
Expand All @@ -145,7 +157,7 @@
{{else}}
{{#with (flattenUnique symbol.members "doc.tparams" "name") as |allTParams|}}
{{#if (ne (len allTParams) 0)}}
=={{#unless @root.config.multipage}}={{/unless}} Parameters
{{#> markup/dynamic-level-h }}Parameters{{/markup/dynamic-level-h}}

|===
| Name | Description
Expand All @@ -162,7 +174,7 @@
{{! Parameters }}
{{#if (ne symbol.kind "overloads")}}
{{#if symbol.doc.params}}
=={{#unless @root.config.multipage}}={{/unless}} Parameters
{{#> markup/dynamic-level-h }}Parameters{{/markup/dynamic-level-h}}

|===
| Name | Description
Expand All @@ -177,7 +189,7 @@
{{else}}
{{#with (flattenUnique symbol.members "doc.params" "name") as |allParams|}}
{{#if (ne (len allParams) 0)}}
=={{#unless @root.config.multipage}}={{/unless}} Parameters
{{#> markup/dynamic-level-h }}Parameters{{/markup/dynamic-level-h}}

|===
| Name | Description
Expand All @@ -193,7 +205,7 @@
{{/if}}
{{! Preconditions }}
{{#if symbol.doc.preconditions}}
=={{#unless @root.config.multipage}}={{/unless}} Preconditions
{{#> markup/dynamic-level-h }}Preconditions{{/markup/dynamic-level-h}}

{{#each symbol.doc.preconditions}}
{{{.}}}
Expand All @@ -202,7 +214,7 @@
{{/if}}
{{! Postconditions }}
{{#if symbol.doc.postconditions}}
=={{#unless @root.config.multipage}}={{/unless}} Postconditions
{{#> markup/dynamic-level-h }}Postconditions{{/markup/dynamic-level-h}}

{{#each symbol.doc.postconditions}}
{{{.}}}
Expand All @@ -211,7 +223,7 @@
{{/if}}
{{! See Also }}
{{#if symbol.doc.see}}
=={{#unless @root.config.multipage}}={{/unless}} See Also
{{#> markup/dynamic-level-h }}See Also{{/markup/dynamic-level-h}}

{{#each symbol.doc.see}}
{{{.}}}
Expand Down
6 changes: 6 additions & 0 deletions share/mrdocs/addons/generator/common/partials/markup/dynamic-level-h.hbs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
{{#> markup/h
level=(select @root.config.multipage (or level 1) (add (or level 1) 1))
id=id
}}
{{> @partial-block }}
{{/markup/h}}
2 changes: 1 addition & 1 deletion share/mrdocs/addons/generator/html/partials/markup/h.html.hbs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1 +1 @@
<h{{or level 3}}{{#if class}} class="{{class}}"{{/if}}>{{> @partial-block }}</h{{or level 3}}>
<h{{or level 3}}{{#if class}} class="{{{class}}}"{{/if}}{{#if id}} id="{{{id}}}"{{/if}}>{{> @partial-block }}</h{{or level 3}}>
45 changes: 29 additions & 16 deletions share/mrdocs/addons/generator/html/partials/symbol.html.hbs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,22 @@
{{!--
Renders the documentation for a symbol in a format that is coherent for all symbol kinds.

This partial conditionally checks if each documentation section exists and if a symbol kind
does not provide a specific kind of documentation section, that section is not rendered.

Expected Context: {Root Context Object}

Example:
{{> symbol }}

See: https://mrdocs.com/docs/mrdocs/develop/generators.html#dom_reference
--}}
{{#unless @root.config.multipage }}
{{! Single page documentation: symbol is not available to the wrapper but it's available here }}
{{! Include the symbol title at a higher level }}
<div id="{{{symbol.anchor}}}">
<div>
<h2>{{> symbol/qualified-name symbol }}</h2>
<div>
{{#> markup/h level=2 id=symbol.anchor }}{{> symbol/qualified-name symbol }}{{/markup/h}}
{{/unless}}
{{! Brief }}
{{#if symbol.doc.brief}}
Expand All @@ -18,7 +31,7 @@
{{! Synopsis }}
{{#unless (contains (arr "namespace") symbol.kind)}}
<div>
<h3>Synopsis</h3>
{{#> markup/dynamic-level-h level=2 }}Synopsis{{/markup/dynamic-level-h}}
<div>
{{>location/source dcl=(primary_location symbol)}}
</div>
Expand Down Expand Up @@ -59,7 +72,7 @@
{{! Members }}
{{#if (and symbol.members (ne symbol.kind "overloads"))}}
<div>
<h3>Members</h3>
{{#> markup/dynamic-level-h level=2 }}Members{{/markup/dynamic-level-h}}
<table>
<thead>
<tr>
Expand Down Expand Up @@ -90,15 +103,15 @@
{{! Description }}
{{#if symbol.doc.description}}
<div>
<h3>Description</h3>
{{#> markup/dynamic-level-h level=2 }}Description{{/markup/dynamic-level-h}}
{{{symbol.doc.description}}}

</div>
{{/if}}
{{! Using symbols }}
{{#if symbol.shadows}}
<div>
<h3>Introduced Symbols</h3>
{{#> markup/dynamic-level-h level=2 }}Introduced Symbols{{/markup/dynamic-level-h}}
<table>
<thead>
<tr>
Expand All @@ -120,7 +133,7 @@
{{#if (ne symbol.kind "overloads")}}
{{#if symbol.doc.exceptions}}
<div>
<h3>Exceptions</h3>
{{#> markup/dynamic-level-h level=2 }}Exceptions{{/markup/dynamic-level-h}}
<table>
<thead>
<tr>
Expand All @@ -143,7 +156,7 @@
{{#with (flattenUnique symbol.members "doc.exceptions" "exception") as |allExceptions|}}
{{#if (ne (len allExceptions) 0)}}
<div>
<h3>Exceptions</h3>
{{#> markup/dynamic-level-h level=2 }}Exceptions{{/markup/dynamic-level-h}}
<table>
<thead>
<tr>
Expand All @@ -167,15 +180,15 @@
{{! Return value }}
{{#if symbol.doc.returns}}
<div>
<h3>Return Value</h3>
{{#> markup/dynamic-level-h level=2 }}Return Value{{/markup/dynamic-level-h}}
{{{symbol.doc.returns}}}
</div>
{{/if}}
{{! Template Parameters }}
{{#if (ne symbol.kind "overloads")}}
{{#if symbol.doc.tparams}}
<div>
<h3>Template Parameters</h3>
{{#> markup/dynamic-level-h level=2 }}Template Parameters{{/markup/dynamic-level-h}}
<table>
<thead>
<tr>
Expand All @@ -198,7 +211,7 @@
{{#with (flattenUnique symbol.members "doc.tparams" "name") as |allTParams|}}
{{#if (ne (len allTParams) 0)}}
<div>
<h3>Template Parameters</h3>
{{#> markup/dynamic-level-h level=2 }}Template Parameters{{/markup/dynamic-level-h}}
<table>
<thead>
<tr>
Expand All @@ -223,7 +236,7 @@
{{#if (ne symbol.kind "overloads")}}
{{#if symbol.doc.params}}
<div>
<h3>Parameters</h3>
{{#> markup/dynamic-level-h level=2 }}Parameters{{/markup/dynamic-level-h}}
<table>
<thead>
<tr>
Expand All @@ -246,7 +259,7 @@
{{#with (flattenUnique symbol.members "doc.params" "name") as |allParams|}}
{{#if (ne (len allParams) 0)}}
<div>
<h3>Parameters</h3>
{{#> markup/dynamic-level-h level=2 }}Parameters{{/markup/dynamic-level-h}}
<table>
<thead>
<tr>
Expand All @@ -270,7 +283,7 @@
{{! Preconditions }}
{{#if symbol.doc.preconditions}}
<div>
<h3>Preconditions</h3>
{{#> markup/dynamic-level-h level=2 }}Preconditions{{/markup/dynamic-level-h}}
{{#each symbol.doc.preconditions}}
<p>{{.}}</p>
{{/each}}
Expand All @@ -279,7 +292,7 @@
{{! Postconditions }}
{{#if symbol.doc.postconditions}}
<div>
<h3>Postconditions</h3>
{{#> markup/dynamic-level-h level=2 }}Postconditions{{/markup/dynamic-level-h}}
{{#each symbol.doc.postconditions}}
<p>{{.}}</p>
{{/each}}
Expand All @@ -288,7 +301,7 @@
{{! See Also }}
{{#if symbol.doc.see}}
<div>
<h3>See Also</h3>
{{#> markup/dynamic-level-h level=2 }}See Also{{/markup/dynamic-level-h}}
{{#each symbol.doc.see}}
<p>{{.}}</p>
{{/each}}
Expand Down
1 change: 1 addition & 0 deletions src/lib/Gen/hbs/Builder.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -160,11 +160,11 @@



Builder::

Check warning on line 163 in src/lib/Gen/hbs/Builder.cpp

View workflow job for this annotation

GitHub Actions / GCC 14: C++20

Build Warning - g++-14 - [-Wreorder] 

g++-14 - when initialized here  ([-Wreorder])

Check warning on line 163 in src/lib/Gen/hbs/Builder.cpp

View workflow job for this annotation

GitHub Actions / GCC 14: C++20 (Coverage)

Build Warning - g++-14 - [-Wreorder] 

g++-14 - when initialized here  ([-Wreorder])
Builder(
HandlebarsCorpus const& corpus,
std::function<void(OutputRef&, std::string_view)> escapeFn)
: domCorpus(corpus)

Check warning on line 167 in src/lib/Gen/hbs/Builder.cpp

View workflow job for this annotation

GitHub Actions / Apple-Clang

Build Warning - clang++ - [-Wreorder-ctor] 

clang++ - field 'domCorpus' will be initialized after field 'escapeFn_'  ([-Wreorder-ctor])

Check warning on line 167 in src/lib/Gen/hbs/Builder.cpp

View workflow job for this annotation

GitHub Actions / Clang 18: C++20

Build Warning - clang++-18 - [-Wreorder-ctor] 

clang++-18 - field 'domCorpus' will be initialized after field 'escapeFn_'  ([-Wreorder-ctor])
, escapeFn_(std::move(escapeFn))
{
namespace fs = std::filesystem;
Expand Down Expand Up @@ -233,6 +233,7 @@
helpers::registerStringHelpers(hbs_);
helpers::registerAntoraHelpers(hbs_);
helpers::registerLogicalHelpers(hbs_);
helpers::registerMathHelpers(hbs_);
helpers::registerContainerHelpers(hbs_);
hbs_.registerHelper("relativize", dom::makeInvocable(relativize_fn));

Expand Down
Loading
Loading