Metamacros
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.
Metamacro Syntax
Metamacros use the syntax !!<NAME>(<TEXT>)
.
- A
!!
double exclamation mark prefix begins a metamacro. <NAME>
must be a valid Julia identifier.(
opening bracket<TEXT>
is optional and can contain arbitrary text.)
closing bracket
Example:
"""
!!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 !!
double
exclamation mark. This does not escape any nested metamacros.
Example:
"""
\\!!hypothetical()
\\!!set(author:Author's Name)
\\!!var(license:[MIT](\\!!var(license_url:https://github.com/LICENSE.md)))
"""
Metamacro definitions
Docile comes with a couple of metamacro definitions in src/Extensions
folder.
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: .docile
.
Return Values
Metamacro methods must return a string which is spliced back into the docstring in place of the
metamacro syntax
.
The returned string, which can also be an empty string, replaces everything starting with
the !!
up to and including the closing parentheses.