API to implement by the actual role directive parser.
Represents a single part (field or body) of a directive.
Represents a single text role implementation.
Type class required for using the generic Builders API with directives.
The public user API for specifying the required and optional parts of a directive (fields or body) together with optional converter/validator functions.
API entry point for setting up a text role that.
API for creating interpreted text roles, the extension mechanism for inline elements of reStructuredText. The API did not aim to mimic the API of the original Python reference implementation. Instead the goal was to create an API that is idiomatic Scala, fully typesafe and as concise as possible. Yet it should be flexible enough to semantically support the options of the Python text roles, so that ideally most existing Python text roles could theoretically get ported to Laika.
Entry point for creating a new role is the
TextRoleobject. It allows to specify the following aspects that define a text role:Spaninstance that the original interpreted text should be replaced with.A role directive may consist of any combination of fields and body elements:
.. role:: ticket(link) :base-url: http://www.company.com/tickets/In the example above
ticketis the name of the customized role,linkthe name of the base role andbase-urlthe value that overrides the default defined in the base role. For the specification details on role directives see http://docutils.sourceforge.net/docs/ref/rst/directives.html#custom-interpreted-text-roles.Before such a role directive can be used, an implementation has to be provided for the base role with the name
link. For more details on implementing directives see laika.parse.rst.Directives.The implementation of the
linktext role could look like this:We specify the name of the role to be
link, and the default value the URL provided as the second argument. The second parameter list specifies the role directive implementation, in this case only consisting of a call tofield("base-url")which specifies a required field of typeString(since no conversion function was supplied). The type of the result of the directive has to match the type of the default value. Finally the role function is defined that accepts two arguments. The first is the base url, either the default in case the base role is used directly, or the value specified with thebase-urlfield in a customized role. The second is the actual text from the interpreted text span. Finally the directive gets registered with theReStructuredTextparser.If you need to define more fields or body content they can be added with the
~combinator just like with normal directives. Likewise you can specify validators and converters for fields and body values like documented in laika.parse.rst.Directives.Our example role can then be used in the following ways:
Using the base role directly:
This would result in the following HTML:
For details read our <a href="http://www.company.com/main/documentation">documentation</a>.Using the customized role called
ticket:For details see ticket :ticket:`344`.This would result in the following HTML:
For details see ticket <a href="http://www.company.com/ticket/344">344</a>.