7.8. Documentation generator

The RST module implements the documentation generation pipeline for daslang. It uses RTTI to introspect modules, types, and functions, then produces reStructuredText output suitable for Sphinx documentation builds.

All functions and symbols are in “rst” module, use require to get access to it.

require daslib/rst

7.8.1. Structures

DocGroup

Group of documentation items.

Fields:

  • name : string - Name of the group.

  • func : array<tuple<fn: Function?;mod: Module?>> - Functions in the group.

  • hidden : bool - Whether the group is hidden.

  • _module : Module? - Module, to which this group belongs.

DocsHook

Hook for RST documentation generation.

Fields:

  • annotationFilter : lambda<(ann: Annotation):bool> - Filter for the supported annotations.

  • afterEnums : lambda<(f: FILE?;was_enums:bool):void> - Additional generation hook after the enumerations.

7.8.2. Document writers

document(name: string; mod: Module?; fname: string; groups: array<DocGroup>; hook: DocsHook = DocsHook())

Generates RST documentation for a single module and writes it to a file.

Arguments:
document_enumeration(doc_file: file; mod: Module?; value: auto): auto

Generates RST documentation for a single enumeration type.

Arguments:
document_enumerations(doc_file: file; mods: array<Module?>): bool

Generates RST documentation for all enumerations in the given modules.

Arguments:
documents(name: string; mods: array<Module?>; fname: string; groups: array<DocGroup>; hook: DocsHook = DocsHook())

Generates RST documentation for multiple modules and writes them to files.

Arguments:

7.8.3. Descriptions

describe_short(expr: Expression?|Expression?): auto

Returns a concise one-line description of an expression or type.

Arguments:

7.8.4. Label makers

7.8.4.1. function_label_file

function_label_file(name: auto; value: TypeDecl?; drop_args: int = 0): auto

Creates a unique, file-name-safe label string for a function.

Arguments:

  • name : auto

  • value : TypeDecl?&

  • drop_args : int

function_label_file(value: FunctionPtr; drop_args: int = 0): string

7.8.5. RST section makers

make_group(name: string; plus: string = "+"): string

Creates a named documentation group with a decorative RST section header.

Arguments:

  • name : string

  • plus : string

7.8.6. Group operations

append_to_group_by_regex(group: DocGroup; mod: Module?; reg: Regex): DocGroup&

Appends functions whose names match a regex to an existing documentation group.

Arguments:

7.8.6.1. group_by_regex

group_by_regex(name: string; mod: Module?; reg: Regex): DocGroup

Groups module items whose names match the provided regular expression under a documentation section.

Arguments:
group_by_regex(name: string; mods: array<Module?>; reg: Regex): DocGroup
hide_group(group: DocGroup): DocGroup

Marks the specified documentation group as hidden so it is excluded from output.

Arguments:

7.8.7. Naming helpers

safe_function_name(name: string): string

Escapes special characters in a function name to produce a safe identifier for RST output.

Arguments:

  • name : string