diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index dfe6f20d1..e9de927da 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -4,6 +4,7 @@ * xref:usage.adoc[Getting Started] * xref:commands.adoc[Documenting the Code] * xref:config-file.adoc[] +* xref:generators.adoc[] * xref:design-notes.adoc[] * xref:contribute.adoc[] * xref:license.adoc[] diff --git a/docs/modules/ROOT/pages/config-file.adoc b/docs/modules/ROOT/pages/config-file.adoc index 1068cf841..9a0c2c453 100644 --- a/docs/modules/ROOT/pages/config-file.adoc +++ b/docs/modules/ROOT/pages/config-file.adoc @@ -11,8 +11,11 @@ include::partial$mrdocs-example.yml[] -------- The xref:usage.adoc[Usage] page provides a detailed explanation of what to combine options from the configuration file and the command line. + The <> section provides a detailed explanation of the options available. +More information about the generators can be found in the xref:generators.adoc[Generators] page. + == YAML Schema To get linting and autocompletion in the config file, a schema for the config can be specified. @@ -44,60 +47,6 @@ When this file is generated from a `CMakeLists.txt` script, the `cmake` option c Additionally, the `defines` option can be used to specify preprocessor definitions that should be used when generating the documentation. These definitions are included in all targets of the compilation database. -== Generators - -MrDocs supports multiple output formats that can be specified via the `generate` option: - -|=== -|Format |Description - -|`adoc` -|AsciiDoc format. - -|`html` -|HTML format. - -|`xml` -|XML format. -|=== - -* Asciidoc is a text-based format that is easy to read and write. -It can also be converted to other formats such as HTML and Markdown. - -* HTML can be generated directly with the `html` format. - -* XML is a structured format that can be used in tests or as an intermediary format for other tools. - -The `generate` option can be used to specify the output format: - -[source,yaml] ----- -# ... -generate: adoc -# ... ----- - -=== Generator Templates - -MrDocs attempts to support various alternatives for customizing the output format and style without complex workflows to post-process XML output. -For the Asciidoc and HTML generators, the desired customization can usually be achieved by modifying the templates used to generate the output. - -In the root of the installation directory, you will find the `share/mrdocs/addons/generator` directory. -This directory contains the templates used to generate the documentation with the markup formats. -Users can create a copy of these files and provide their own `addons` directory via the `addons` option. -This allows users to customize the output format to their needs. - -[source,yaml] ----- -addons: /path/to/custom/addons ----- - -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. - -// === Generator Plugins - == Filters === Symbol Filters diff --git a/docs/modules/ROOT/pages/generators.adoc b/docs/modules/ROOT/pages/generators.adoc new file mode 100644 index 000000000..1018d4fe8 --- /dev/null +++ b/docs/modules/ROOT/pages/generators.adoc @@ -0,0 +1,854 @@ += Generators + +MrDocs uses a generator to convert the extracted symbols into documentation. MrDocs supports multiple output formats that can be specified via the `generate` option: + +The `generate` option can be used to specify the output format: + +[source,yaml] +---- +# ... +generate: adoc +# ... +---- + +Three output formats are supported: + +|=== +|Format |Description + +|`adoc` +|AsciiDoc format. + +|`html` +|HTML format. + +|`xml` +|XML format. +|=== + +The corpus of symbols is provided to the generator responsible for converting these symbols into the desired output format. + +The `xml` generator is used as an intermediary format for other tools or for testing purposes. Users can write their own tools to process the XML output and generate custom documentation. + +The `adoc` and `html` generators use templates to generate the documentation. These templates can be customized to change the output format and style. + +Asciidoc is a text-based format that is easy to read and write. It can also be converted to other formats such as HTML and Markdown. + +HTML can be generated directly with the `html` format. + +== Generator Templates + +MrDocs attempts to support various alternatives for customizing the output format and style without complex workflows to post-process XML output. The `adoc` and `html` generators use https://handlebarsjs.com/[Handlebars,window=_blank] templates. These templates can be customized to change the output format and style of the documentation. + +The templates used to generate the documentation are located in the `share/mrdocs/addons/generator` directory. Users can create a copy of these files and provide their own `addons` directory via the `addons` option in the configuration file or via the command line. + +[source,yaml] +---- +addons: /path/to/custom/addons +---- + +Each symbol goes through a main layout template in the `share/mrdocs/addons/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 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. + +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. + +== Document Object Model Reference + +The Document Object Model (DOM) is a tree structure that represents the symbols extracted from the source code. The DOM is used by the generator to render the documentation. + +=== Top-Level Fields + +The top-level object in the DOM is the context for a template. The top-level object has the following properties: + +|=== +|Property |Type| Description + +|`symbol` +|`<>` +|The symbol being rendered. + +|`relfileprefix` +|`string` +|The relative file prefix for the output file. + +|`config` +|`<>` +|The configuration object. + +|`sectionref` +|`string` +|The section reference. +|=== + +[#symbol-fields] +=== Symbol + +The `Symbol` object represents a symbol extracted from the source code.The symbol being rendered is available in the `symbol` object in the Handlebars context.The symbol object has the following properties: + +|=== +|Property |Type| Description + +| `id` +| `string` +| A unique identifier for the symbol. + +| `name` +| `string` +| The nonqualified name of the symbol. + +| `kind` +| `string` +| The kind of symbol. (e.g., `class`, `function`, `variable`) + +| `access` +| `string` +| The access level of the symbol. (e.g., `public`, `protected`, `private`) + +| `implicit` +| `string` +| Whether the symbol was implicitly extracted as a dependency. + +| `namespace` +| `<>` +| The namespaces of the symbol. + +| `parent` +| `<>` +| The parent namespace of the symbol. + +| `doc` +| `Any` +| The documentation for the symbol. + +|=== + +The `Symbol` object has additional properties based on the kind of symbol. The following table lists the additional properties for symbols that contain information about their scope (such as Namespaces and Classes): + +|=== +|Property |Type| Description + +| `members` +| `<>` +| The members of that scope (e.g., member functions, namespace symbols). + +| `overloads` +| `<>` +| Same as `members`, but groups overloaded functions as unique symbols of kind `overload`. +|=== + +Symbol objects that contain information about the location include the following properties: + +|=== +|Property |Type| Description + +| `loc` +| `<>` +| The location of the symbol in the source code. +|=== + +When the symbol kind is `namespace`, the symbol object has the following additional properties: + +|=== +|Property |Type| Description + +| `interface` +| `<>` +| The interface of the namespace. + +| `usingDirectives` +| `<>` +| The using directives of the namespace. +|=== + +When the symbol kind is `record` (e.g., `class`, `struct`, `union`), the symbol object has the following additional properties: + +|=== +|Property |Type| Description + +| `tag` +| `string` +| The type of record (e.g., `class`, `struct`, `union`). + +| `defaultAccess` +| `string` +| The default access level of the record members (e.g., `public`, `private`). + +| `isTypedef` +| `bool` +| Whether the record is a typedef. + +| `bases` +| `<>` +| The base classes of the record. + +| `interface` +| `<>` +| The interface of the record. + +| `template` +| `<>` +| The template information of the record. +|=== + +When the symbol kind is `enum`, the symbol object has the following additional properties: + +|=== +|Property |Type| Description + +| `type` +| `<>` +| The type information of the enum. + +| `isScoped` +| `bool` +| Whether the enum is scoped. +|=== + +When the symbol kind is `function`, the symbol object has the following additional properties: + +|=== +|Property |Type| Description + +| `isVariadic` +| `bool` +| Whether the function is variadic. + +| `isVirtual` +| `bool` +| Whether the function is virtual. + +| `isVirtualAsWritten` +| `bool` +| Whether the function is virtual as written. + +| `isPure` +| `bool` +| Whether the function is pure. + +| `isDefaulted` +| `bool` +| Whether the function is defaulted. + +| `isExplicitlyDefaulted` +| `bool` +| Whether the function is explicitly defaulted. + +| `isDeleted` +| `bool` +| Whether the function is deleted. + +| `isDeletedAsWritten` +| `bool` +| Whether the function is deleted as written. + +| `isNoReturn` +| `bool` +| Whether the function is noreturn. + +| `hasOverrideAttr` +| `bool` +| Whether the function has the override attribute. + +| `hasTrailingReturn` +| `bool` +| Whether the function has a trailing return type. + +| `isConst` +| `bool` +| Whether the function is const. + +| `isVolatile` +| `bool` +| Whether the function is volatile. + +| `isFinal` +| `bool` +| Whether the function is final. + +| `isNodiscard` +| `bool` +| Whether the function is nodiscard. + +| `isExplicitObjectMemberFunction` +| `bool` +| Whether the function is an explicit object member function. + +| `constexprKind` +| `string` +| The constexpr kind of the function (e.g., `consteval`, `constexpr`). + +| `storageClass` +| `string` +| The storage class of the function (e.g., `static`, `extern`). + +| `refQualifier` +| `string` +| The reference qualifier of the function (e.g., `&`, `&&`). + +| `class` +| `string` +| The function class (e.g., `constructor`, `conversion`, `destructor`). + +| `params` +| `<>` +| The parameters of the function. + +| `return` +| `<>` +| The return type of the function. + +| `template` +| `<>` +| The template information of the function. + +| `overloadedOperator` +| `string` +| The overloaded operator of the function. + +| `exceptionSpec` +| `string` +| The exception specification of the function. + +| `explicitSpec` +| `string` +| The explicit specification of the function. + +| `requires` +| `string` +| The `requires` expression of the function. +|=== + +When the symbol kind is `typedef`, the symbol object has the following additional properties: + +|=== +| Property | Type | Description + +| `type` +| `<>` +| The type information of the typedef. + +| `template` +| `<>` +| The template information of the typedef. + +| `isUsing` +| `bool` +| Whether the typedef is a `using` declaration. +|=== + +When the symbol kind is `variable`, the symbol object has the following additional properties: + +|=== +| Property | Type | Description + +| `type` +| `<>` +| The type information of the variable. + +| `template` +| `<>` +| The template information of the variable. + +| `constexprKind` +| `string` +| The constexpr kind of the variable (e.g., `consteval`, `constexpr`). + +| `storageClass` +| `string` +| The storage class of the variable (e.g., `static`, `extern`). + +| `isConstinit` +| `bool` +| Whether the variable is `constinit`. + +| `isThreadLocal` +| `bool` +| Whether the variable is thread-local. + +| `initializer` +| `string` +| The initializer of the variable. +|=== + +When the symbol kind is `field` (i.e. non-static data members), the symbol object has the following additional properties: + +|=== +| Property | Type | Description + +| `type` +| `<>` +| The type information of the field. + +| `default` +| `string` +| The default value of the field. + +| `isMaybeUnused` +| `bool` +| Whether the field is maybe unused. + +| `isDeprecated` +| `bool` +| Whether the field is deprecated. + +| `isVariant` +| `bool` +| Whether the field is a variant. + +| `isMutable` +| `bool` +| Whether the field is mutable. + +| `isBitfield` +| `bool` +| Whether the field is a bitfield. + +| `hasNoUniqueAddress` +| `string` +| Whether the field has the `[[no_unique_address]]` attribute. + +| `bitfieldWidth` +| `string` +| The width of the bitfield. +|=== + +When the symbol kind is `friend`, the symbol object has the following additional properties: + +|=== +| Property | Type | Description + +| `name` +| `string` +| The name of the friend symbol or type. + +| `symbol` +| <> +| The friend symbol. + +| `type` +| <> +| The friend type. +|=== + +When the symbol kind is `alias`, the symbol object has the following additional properties: + +|=== +| Property | Type | Description + +| `aliasedSymbol` +| <> +| The aliased symbol. +|=== + +When the symbol kind is `using`, the symbol object has the following additional properties: + +|=== +| Property | Type | Description + +| `class` +| `string` +| The class of the using declaration (e.g., `normal`, `typename`, `enum`). + +| `shadows` +| <> +| The symbols being used. + +| `qualifier` +| `<>` +| The qualifier of the using declaration. +|=== + +When the symbol kind is `enumerator`, the symbol object has the following additional properties: + +|=== +| Property | Type | Description + +| `initializer` +| `string` +| The initializer of the enumerator. +|=== + +When the symbol kind is `guide`, the symbol object has the following additional properties: + +|=== +| Property | Type | Description + +| `params` +| `<>` +| The parameters of the guide. + +| `deduced` +| `<>` +| The deduced type of the guide. + +| `template` +| `<>` +| The template information of the guide. + +| `explicitSpec` +| `string` +| The explicit specification of the guide. +|=== + +When the symbol kind is `concept`, the symbol object has the following additional properties: + +|=== +| Property | Type | Description + +| `template` +| `<>` +| The template information of the concept. + +| `constraint` +| `string` +| The constraint of the concept. +|=== + +[#source-info-fields] +=== Source Info Fields + +The `Source Info` object represents the location of the symbol in the source code. The source info object has the following properties: + +|=== +|Property |Type| Description + +| `def` +| <> +| Location where the entity was defined. + +| `decl` +| <> +| Locations where the entity was declared. +|=== + +[#tranche-fields] +=== Tranche Object Fields + +The `Tranche` object represents the symbols in a scope (e.g., namespace). The tranche object has the following properties: + +|=== +|Property |Type| Description + +| (symbol kind in plural form: e.g., `classes`, `functions`, `variables`) +| `<>` +| The symbols of that kind in the scope. + +| `types` +| `<>` +| The types in the scope. + +| `staticfuncs` +| `<>` +| The static functions in the scope. + +| `overloads` +| `<>` +| The overloads in the scope. + +| `staticoverloads` +| `<>` +| The static overloads in the scope. +|=== + +[#interface-fields] +=== Interface Object Fields + +The `Interface` object represents the interface of a record (e.g., class, struct, union). The interface object has the following properties: + +|=== +|Property |Type| Description + +| `public` +| `<>` +| The public interface of the record. + +| `protected` +| `<>` +| The protected interface of the record. + +| `private` +| `<>` +| The private interface of the record. +|=== + +[#base-info-fields] +=== Base Info Fields + +The `Base Info` object represents a base class of a record. The base info object has the following properties: + +|=== +|Property |Type| Description + +| `access` +| `string` +| The access level of the base class. + +| `isVirtual` +| `bool` +| Whether the base class is virtual. + +| `type` +| `<>` +| The type information of the base class. +|=== + +[#template-info-fields] +=== Template Info Fields + +The `Template Info` object represents the template information of a record, function, or typedef. The template info object has the following properties: + +|=== +|Property |Type| Description + +| `kind` +| `string` +| The kind of template (e.g., `explicit`, `partial`). + +| `primary` +| `<>` +| The primary template. + +| `params` +| `<>` +| The template parameters. + +| `args` +| `<>` +| The template arguments. + +| `requires` +| `string` +| The `requires` expression of the template. +|=== + +[#type-info-fields] +=== Type Info Fields + +The `Type Info` object represents the type information of a symbol. The type info object has the following properties: + +|=== +|Property |Type| Description + +| `kind` +| `string` +| The kind of type (e.g., `named`, `decltype`, `auto`, `pointer`, `reference`, `array`, `function`). + +| `is-pack` +| `bool` +| Whether the type is a pack expansion. + +| `name` +| `string` +| The name of the type. + +| `operand` +| `string` +| The operand of the type. + +| `keyword` +| `string` +| The keyword of the type. + +| `constraint` +| `string` +| The constraint of the type. + +| `cv-qualifiers` +| `string` +| The cv qualifier of the type (e.g., `const`, `volatile`). + +| `parent-type` +| `<>` +| The parent type of the type. + +| `pointee-type` +| `<>` +| The pointee type of the type. + +| `element-type` +| `<>` +| The element type of the type. + +| `bounds-value` +| `string` +| The bounds value of the type. + +| `bounds-expr` +| `string` +| The bounds expression of the type. + +| `return-type` +| `<>` +| The return type of the type. + +| `param-types` +| `<>` +| The parameter types of the type. + +| `exception-spec` +| `string` +| The exception specification of the type. + +| `ref-qualifier` +| `string` +| The reference qualifier of the type. + +| `is-variadic` +| `bool` +| Whether the type is variadic. +|=== + +[#param-fields] +=== Param Fields + +The `Param` object represents the parameter of a function. The param object has the following properties: + +|=== +|Property |Type| Description + +| `name` +| `string` +| The name of the parameter. + +| `type` +| `<>` +| The type information of the parameter. + +| `default` +| `string` +| The default value of the parameter. +|=== + +[#name-info-fields] +=== Name Info Fields + +The `Name Info` object represents the name of a symbol. The name info object has the following properties: + +|=== +|Property |Type| Description + +| `name` +| `string` +| The name of the symbol. + +| `symbol` +| `string` +| The unique identifier of the symbol. + +| `args` +| `<>` +| The template arguments of the symbol. + +| `prefix` +| `string` +| The prefix of the symbol. +|=== + +[#location-fields] +=== Location Fields + +The `Location` object represents the location of a symbol in the source code. The location object has the following properties: + +|=== +|Property |Type| Description + +| `path` +| `string` +| The path of the source file. + +| `file` +| `string` +| The filename of the source file. + +| `line` +| `integer` +| The line number of the symbol. + +| `kind` +| `string` +| The kind of file (e.g., `source`, `system`, `other`). + +| `documented` +| `bool` +| Whether the symbol is documented. +|=== + +[#tparam-fields] +=== TParam Fields + +The `TParam` object represents a template parameter of a record, function, or typedef. The tparam object has the following properties: + +|=== +|Property |Type| Description + +| `kind` +| `string` +| The kind of template parameter (e.g., `type`, `non-type`, `template`). + +| `name` +| `string` +| The name of the template parameter. + +| `is-pack` +| `bool` +| Whether the template parameter is a pack expansion. + +| `default` +| `string` +| The default value of the template parameter. + +| `key` +| `string` +| The key kind of the template parameter. + +| `constraint` +| `string` +| The constraint of the template parameter. + +| `type` +| `<>` +| The type information of the template parameter. + +| `params` +| `<>` +| The template parameters of the template parameter. +|=== + +[#targ-fields] +=== Targ Fields + +The `Targ` object represents a template argument of a record, function, or typedef. The targ object has the following properties: + +|=== +|Property |Type| Description + +| `kind` +| `string` +| The kind of template argument (e.g., `type`, `non-type`, `template`). + +| `is-pack` +| `bool` +| Whether the template argument is a pack expansion. + +| `type` +| `<>` +| The type information of the template argument. + +| `value` +| `string` +| The value of the template argument. + +| `name` +| `string` +| The name of the template argument. + +| `template` +| `<>` +| The template information of the template argument. +|=== + +[#config-fields] +=== Config Fields + +The `Config` object represents the configuration object. It includes all values provided to MrDocs in the configuration file or via the command line. Please refer to the xref:config-file.adoc[configuration file reference] for more information. diff --git a/include/mrdocs/Metadata/Source.hpp b/include/mrdocs/Metadata/Source.hpp index 37c397fa3..bfe79106b 100644 --- a/include/mrdocs/Metadata/Source.hpp +++ b/include/mrdocs/Metadata/Source.hpp @@ -86,6 +86,7 @@ struct MRDOCS_DECL } }; +MRDOCS_DECL void tag_invoke( dom::ValueFromTag,