TalonDoc

Documentation for TalonDoc

Loading a Talon package

TalonDoc can analyse a Talon package or user directory. To load all Talon and Python files in example/knausj_talon we add the following to conf.py:

talon_package = {
  'path': '../knausj_talon',
  'name': 'user',
  'exclude': ['conftest.py', 'test/**'],
  'trigger': 'ready'
}

The talon_package value is required and describes the Talon package that is being documented. It should be a dictionary with the key path whose value is the path to the root directory of the Talon package. The path may be relative to the conf.py file. The dictionary may optionally contain any of the following keys:

name: The name of the Talon package. This is used to resolve self.* references. Defaults to user.
include: A list of glob patterns. All .talon and .py files in the package directory are included by default, but any file matched by an include pattern will be included even if it matches any of the patterns in exclude.
exclude: A list of glob patterns. Any file matched by an exclude pattern will be excluded unless it matches any of the patterns in include.
trigger: A list of Talon events. These events will be triggered after the entire package has been loaded. Useful for making sure that “launch” and “ready” callbacks fire.

If the talon_package value is a string, and not a dictionary, it is interpreted as the value of the path field.

If you wish to document multiple Talon packages, you can use talon_packages whose value must be a list or tuple of package descriptions as described above.

Warning

Sphinx can work with either reStructuredText or Markdown, but in order to work with Markdown you need to add the following to your conf.py:

extensions = [
    # Enables support for Markdown
    # https://www.sphinx-doc.org/en/master/usage/markdown.html
    "myst_parser",

    # Other extensions
    # ...
]

Furthermore, in order to use the colon fence syntax (:::) used throughout this guide, you need to enable the colon_fence extension, by adding the following to your conf.py:

myst_enable_extensions = [
    # Enables colon fence directives
    # https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#syntax-colon-fence
    "colon_fence",

    # Other extensions
    # ...
]

For more information, see the Sphinx documentation and the MyST documentation.

Commands

Individual Commands

TalonDoc can generate documentation for an individual command using talon:command by entering any phrase which triggers the command. For instance, the following code:

.. talon:command:: hunt this
:always_include_script:

.. talon:command:: hunt this pace
:always_include_script:

:::{talon:command} hunt this
:always_include_script:
:::

:::{talon:command} hunt this pace
:always_include_script:
:::

…will generate the following bit of documentation:

hunt this

Finds text in current editor

user.find("")

hunt this (pace | paste)

Finds text in current editor

user.find("")
sleep(25ms)
edit.paste()

TalonDoc will attempt to generate documentation for the command using the following three options, in order:

Use the Talon docstrings in the command script. Talon docstrings are comments which start with ###.
Use the Python docstrings from the actions used in the command script.
Include the command script.

The talon:command directive take the following options:

:always_include_script:: If specified, the literal script is always included in the command description.
:context: and :contexts:: The contexts in which to search for the command. Contexts can be specified using Talon context names, e.g., user.apps.discord.discord or user.apps.discord.discord.talon, or by using file names relative to the package root, e.g., apps/discord/discord.talon. Multiple contexts can be specified, in which case they should be separated by commas. If neither :context: nor :contexts: is specified, all commands are searched.

If the command is ambiguous it is necessary to specify the context. For instance, the command ‘decline call’ matches multiple commands in different contexts. Therefore, the following code will raise an error:

.. talon:command:: answer call
.. talon:command:: decline call

:::{talon:command} answer call
:::
:::{talon:command} decline call
:::

…and it generates the following bad documentation. It inserts the ambiguous command verbatim, and does not generate any other documentation for it:

answer call: Answer incoming call

decline call

To generate the correct documentation you must specify the context in which it is defined. For example, the following code:

.. talon:command:: answer call
.. talon:command:: decline call
:context: user.apps.discord.discord

:::{talon:command} answer call
:::
:::{talon:command} decline call
:context: user.apps.discord.discord
:::

…will generate the following, much better looking documentation:

answer call: Answer incoming call

decline call: Decline incoming call

Tables of commands

TalonDoc can generate documentation for groups of commands via talon:command-table, which generates a table with two columns—the rule and the description as those generated by talon:command.

For instance, the following code:

.. talon:command-table::
:caption: A little custom hunting table.
:include: hunt this, hunt this pace

.. talon:command-table::
:caption: A bigger custom Discord table.
:context: user.apps.discord.discord

:::{talon:command-table}
:caption: A little custom hunting table.
:include: hunt this, hunt this pace
:::

:::{talon:command-table}
:caption: A bigger custom Discord table.
:context: user.apps.discord.discord
:::

… generates the following two tables:

A little custom hunting table.
hunt this	Finds text in current editor
hunt this (pace \| paste)	Finds text in current editor

A bigger custom Discord table.
{user.discord_destination} [<user.text>]	Open up the quick switcher, optionally specifying a type of destination
switcher	Open up the quick switcher, optionally specifying a type of destination
[channel] mentions last	Go up to channel with unread mentions
[channel] mentions next	Go down to channel with unread mentions
oldest unread	Go to oldest unread message
current call	Go to current call
toggle pins	Toggle pins popout
toggle inbox	Toggle inbox popout
toggle (members \| member list)	Toggle channel member list
toggle (dee ems \| dims)	Toggle between dms and your most recent server
pick emoji	Toggle emoji picker
pick (jif \| gif \| gift)	Toggle gif picker
pick sticker	Toggle sticker picker
mark inbox channel read	Mark top inbox channel read
[toggle] (mute \| unmute)	Toggle mute
(mute \| unmute) and sleep	Toggle mute Disable speech recognition
[toggle] (deafen \| undeafen)	Toggle deafen
answer call	Answer incoming call
decline call	Decline incoming call

The talon:command-table directive take any number of arguments, which can either be file paths relative to the package root, e.g., apps/discord/discord.talon, or module names, e.g., user.apps.discord.discord.talon. For the latter, the .talon suffix is optional. If no arguments are given, commands are included from the entire package. Furthermore, these directives take the following options:

:always_include_script:: If specified, the literal script is always included in the command description.
:context: and :contexts:: The contexts in which to search for the commands. Contexts can be specified using Talon context names, e.g., user.apps.discord.discord or user.apps.discord.discord.talon, or by using file names relative to the package root, e.g., apps/discord/discord.talon. Multiple contexts can be specified, in which case they should be separated by commas. If neither :context: nor :contexts: is specified, all commands are searched.
:caption:: A caption for the table. Defaults to the module name, if given.
:include:: A list of command phrases. If :include: is specified, all commands matching one of these phrases are included. Otherwise, all commands are included.
:exclude:: A list of command phrases. If :exclude: is specified, any commands matching one of these phrases are excluded.

Actions

TalonDoc can generate documentation for actions using talon:action. For instance, the following code:

.. talon:action:: user.find
.. talon:action:: user.insert_formatted

:::{talon:action} user.find
:::

:::{talon:action} user.insert_formatted
:::

…will generate the following bit of documentation:

user.find(text: str): Finds text in current editor

user.insert_formatted(phrase: str | ..., formatters: str): Inserts a phrase formatted according to formatters. Formatters is a comma separated list of formatters (e.g. 'CAPITALIZE_ALL_WORDS,DOUBLE_QUOTED_STRING')

Captures

TalonDoc can generate documentation for captures using talon:capture. For instance, the following code:

.. talon:capture:: user.any_alphanumeric_key

:::{talon:capture} user.any_alphanumeric_key
:::

…will generate the following bit of documentation:

user.any_alphanumeric_key: str: (<self.letter> | <self.number_key> | <self.symbol_key>); any alphanumeric key

Lists

TalonDoc can generate documentation for lists using talon:list. For instance, the following code:

.. talon:list:: user.letter
.. talon:list:: user.symbol_key

:::{talon:list} user.letter
:::
:::{talon:list} user.symbol_key
:::

…will generate the following bit of documentation:

user.letter

The spoken phonetic alphabet

'air'	'a'
'bat'	'b'
'cap'	'c'
'drum'	'd'
'each'	'e'
'fine'	'f'
'gust'	'g'
'harp'	'h'
'sit'	'i'
'jury'	'j'
'crunch'	'k'
'look'	'l'
'made'	'm'
'near'	'n'
'odd'	'o'
'pit'	'p'
'quench'	'q'
'red'	'r'
'sun'	's'
'trap'	't'
'urge'	'u'
'vest'	'v'
'whale'	'w'
'plex'	'x'
'yank'	'y'
'zip'	'z'

user.symbol_key

All symbols from the keyboard

'dot'	'.'
'point'	'.'
'quote'	"'"
'question'	'?'
'apostrophe'	"'"
'L square'	'['
'left square'	'['
'square'	'['
'R square'	']'
'right square'	']'
'slash'	'/'
'backslash'	'\\'
'minus'	'-'
'dash'	'-'
'equals'	'='
'plus'	'+'
'grave'	'`'
'tilde'	'~'
'bang'	'!'
'down score'	'_'
'underscore'	'_'
'paren'	'('
'brace'	'{'
'left brace'	'{'
'brack'	'{'
'bracket'	'{'
'left bracket'	'{'
'r brace'	'}'
'right brace'	'}'
'r brack'	'}'
'r bracket'	'}'
'right bracket'	'}'
'angle'	'<'
'left angle'	'<'
'less than'	'<'
'rangle'	'>'
'R angle'	'>'
'right angle'	'>'
'greater than'	'>'
'star'	'*'
'hash'	'#'
'percent'	'%'
'caret'	'^'
'amper'	'&'
'pipe'	'\|'
'dub quote'	'"'
'double quote'	'"'
'dollar'	'$'
'pound'	'£'
'`'	'`'
','	','
'back tick'	'`'
'comma'	','
'coma'	','
'period'	'.'
'full stop'	'.'
'semicolon'	';'
'colon'	':'
'forward slash'	'/'
'question mark'	'?'
'exclamation mark'	'!'
'exclamation point'	'!'
'asterisk'	'*'
'hash sign'	'#'
'number sign'	'#'
'percent sign'	'%'
'at sign'	'@'
'and sign'	'&'
'ampersand'	'&'
'dollar sign'	'$'
'pound sign'	'£'
'hyphen'	'-'
'L paren'	'('
'left paren'	'('
'R paren'	')'
'right paren'	')'

Modes

TalonDoc can generate documentation for modes using talon:mode. For instance, the following code:

.. talon:mode:: command
.. talon:mode:: dictation

:::{talon:mode} command
:::
:::{talon:mode} dictation
:::

…will generate the following bit of documentation:

command: Voice commands

dictation: Direct speech to text

Settings

TalonDoc can generate documentation for settings using talon:setting. For instance, the following code:

.. talon:setting:: key_hold

:::{talon:setting} key_hold
:::

…will generate the following bit of documentation:

key_hold: float: milliseconds to wait between key press and release

dictate.punctuation: list = '.,-!?'

Setting documentation is restricted to names and descriptions.

Tags

TalonDoc can generate documentation for tags using talon:tag. For instance, the following code:

.. talon:tag:: user.find_and_replace

:::{talon:tag} user.find_and_replace
:::

…will generate the following bit of documentation:

user.find_and_replace: Tag for enabling generic find and replace commands