Note: Not implemented on develop at the moment.
If you pass a file that is not a source file, it will be treated as template file and processed. This allows advanced control over the output or writing additional documentation files.
standardese will read the file and replace two things:
URLs with the standardese:// protocol will be converted to the correct URL for the given entity.
This allows referring to documentation entities from other files without manually having to deal with the URLs.
Special commands inside two curly braces by default (‘{{ … }}’).
Note: standardese is dumb and does not do any other formatting with the template file otherwise. Most importantly, it will create lot of unnecessary empty lines, so does not really work with formats where newlines are important.
The special commands allow querying standardese for information.
It will look for delimiters and commands starting with standardese_.
All other commands will be silently ignored.
This allows mixing “normal” template syntax with standardese syntax. Process the file with standardese, then your template engine.
There are the following commands available,
entity always means the unique name of an entity here.
standardese_doc <entity> <format>: Will be replaced with the documentation output for entity in the given format.
For example {{ standardese_doc file.hpp html }} will be replaced with the same HTML standardese will generate for the header file file.hpp.
standardese_doc_text <entity> <format>: Will be replaced with the comment of entity in the given format.
standardese_doc_synopsis <entity> <format>: Will be replaced with the synopsis of entity in the given format.
standardese_doc_anchor <unique_name> <format>: If unique_name refers to an existing entity, all links to that entity will link to the anchor in the template file generated in the given format.
Otherwise it will create a new entity named unique_name you can link to throughout the documentation.
standardese_name/index_name/unique_name <entity>: Will be replaced with the name/index name/unique name of the given entity (just a raw character sequence without formatting).
standardese_module: Will be replaced by the module name of the given entity (just a raw character sequence without formatting).
standardese_for <variable> <entity>: Will loop over each child of entity and copy the processed next block, the unique name of the current child is stored in the given variable. For example, this will print the names of all children of an entity:
{{ standardese_for $child some_entity }}
{{ standardese_name $child }}
{{ standardese_end }}
standardese_if/else_if/else <entity> <op> [args...]: Will ignore a block if a condition is not fulfilled. See below for a list of conditions. For example, this will do something different depending on the unique name of an entity:
{{ standardese_if $entity name a }}
Name is a!
{{ standardese_else_if $entity name b }}
Name is b!
{{ standardese_else }}
Name is something else.
{{ standardese_end }}
standardese_end: Ends the block that was started last.
There are the following if operations available:
<entity> name <name>: Checks if entity has the given unique name.
<child> first_child <parent>: Checks if child is the first child of parent.
<entity> has_children: Checks if entity has children.
<entity> inline_entity: Checks if entity is an inline entity (parameter, base class, enum value,…) and inline entities will be shown inline in the documentation output (output.inline_doc).
<entity> member_group: Checks if entity refers to a member group.
<entity> index: Check if entity refers to an index file
You can also provide a default template that can be used to customize the output globally.
Then there are two special variables available: $file, which refers to the current file, and $format, which refers to the set output format.
The most basic template will just generate the output as standardese would do normally:
{{ standardese_doc $file $format }}