Docile provides a user-extensible text substitution macro system, called "metamacros", that can be used to perform arbitrary textual manipulation and replacement in docstrings prior to parsing and displaying them. A metamacro also provides access to the object and module associated with the docstring in which it is written.
Metamacros use the syntax
!!double exclamation mark prefix begins a metamacro.
<NAME>must be a valid Julia identifier.
<TEXT>is optional and can contain arbitrary text.
""" !!hypothetical() !!set(author:Author's Name) !!get(author) !!var(author:Author's Name) !!summary(Set the value for a field in an object's metadata.) !!longform( ... ) !!include(includes/file.md) Nested: !!var(license:[MIT](!!var(license_url:https://github.com/LICENSE.md))) """
Escape for the metamacro syntax
To escape the metamacro syntax a double backslash is used immidiately before the
exclamation mark. This does not escape any nested metamacros.
""" \\!!hypothetical() \\!!set(author:Author's Name) \\!!var(license:[MIT](\\!!var(license_url:https://github.com/LICENSE.md))) """
Docile comes with a couple of metamacro definitions in
Package authors can add their own to customise how their documentation is presented to users.
For example such definitions can be added to a docile package configuration file:
Metamacro methods must return a string which is spliced back into the docstring in place of the
The returned string, which can also be an empty string, replaces everything starting with
!! up to and including the closing parentheses.