From 597727ad3fe675d2940dcef9d962845927aa7751 Mon Sep 17 00:00:00 2001 From: Kendon Bell Date: Sat, 21 Mar 2026 20:12:29 +1300 Subject: [PATCH 1/2] Document remaining language and geometry APIs --- documentation/geometry_classes.txt | 20 ++++++++ documentation/kaldi_engine.txt | 1 + documentation/language.txt | 79 ++++++++++++++++++++++++++++- documentation/related_resources.txt | 4 +- documentation/windows.txt | 4 +- dragonfly/language/base/digits.py | 7 +++ dragonfly/language/base/integer.py | 14 +++++ dragonfly/language/base/number.py | 8 +++ dragonfly/windows/point.py | 6 +++ dragonfly/windows/rectangle.py | 8 +++ 10 files changed, 147 insertions(+), 4 deletions(-) create mode 100644 documentation/geometry_classes.txt diff --git a/documentation/geometry_classes.txt b/documentation/geometry_classes.txt new file mode 100644 index 00000000..0678388f --- /dev/null +++ b/documentation/geometry_classes.txt @@ -0,0 +1,20 @@ +Geometry classes +============================================================================ + +Dragonfly's window and monitor APIs use a pair of small geometry classes to +represent points, bounds and movement calculations across supported +platforms. + + +Point class +---------------------------------------------------------------------------- + +.. autoclass:: dragonfly.windows.point.Point + :members: + + +Rectangle class +---------------------------------------------------------------------------- + +.. autoclass:: dragonfly.windows.rectangle.Rectangle + :members: diff --git a/documentation/kaldi_engine.txt b/documentation/kaldi_engine.txt index 83d8dbc2..ee86811d 100644 --- a/documentation/kaldi_engine.txt +++ b/documentation/kaldi_engine.txt @@ -197,6 +197,7 @@ The engine can also be configured via the :ref:`command-line interface .. autofunction:: dragonfly.engines.backend_kaldi.engine.KaldiEngine + :no-index: **Arguments (all optional):** diff --git a/documentation/language.txt b/documentation/language.txt index a917e824..e2e92dc2 100644 --- a/documentation/language.txt +++ b/documentation/language.txt @@ -135,13 +135,90 @@ The following languages are supported: English has additional time, date and character related classes. +Numeric language elements +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Dragonfly exposes a small public numeric language API through the +:mod:`dragonfly.language` package. These classes use the current speech +recognition engine language to load the right spoken-number content. + +Use the direct element classes when building grammars inline: + +* :class:`Integer` for bounded spoken integers. +* :class:`Digits` for sequences of spoken digits. +* :class:`Number` for larger spoken numbers and number series. + +Use the ``*Ref`` variants when you want Dragonfly to wrap those elements in +named private rules for use as command extras: + +* :class:`IntegerRef` +* :class:`ShortIntegerRef` +* :class:`DigitsRef` +* :class:`NumberRef` + +:class:`ShortIntegerRef` uses a more permissive short-number grammar when a +language implements it and otherwise falls back to normal integer +pronunciations for that language. + + Language classes reference ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. automodule:: dragonfly.language.en.short_number +Integer class ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. autoclass:: dragonfly.language.Integer + :members: + + +IntegerRef class ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. autoclass:: dragonfly.language.IntegerRef :members: +ShortIntegerRef class ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. autoclass:: dragonfly.language.ShortIntegerRef + :members: + + +Digits class ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. autoclass:: dragonfly.language.Digits + :members: + + +DigitsRef class ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. autoclass:: dragonfly.language.DigitsRef + :members: + + +Number class ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. autoclass:: dragonfly.language.Number + :members: + + +NumberRef class ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. autoclass:: dragonfly.language.NumberRef + :members: + + +Short number pronunciation notes ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. automodule:: dragonfly.language.en.short_number + + .. rubric:: References .. [#f1] https://nuance.custhelp.com/app/answers/detail/a_id/6280/kw/Dragon%20NaturallySpeaking%20languages%20supported/related/1 diff --git a/documentation/related_resources.txt b/documentation/related_resources.txt index de9d5dec..43075d99 100644 --- a/documentation/related_resources.txt +++ b/documentation/related_resources.txt @@ -35,8 +35,8 @@ The following resources are used by the Dragonfly community and speech recognition users/developers: * `Gitter chat room `__ - (also `bridged to Matrix `__) - --- Real-time chat and historical discussions about Dragonfly + (also `bridged to Matrix `__) + --- Real-time chat and historical discussions about Dragonfly * `Dragonfly Speech Google Group `_ diff --git a/documentation/windows.txt b/documentation/windows.txt index c162fbf3..c94ba1e5 100644 --- a/documentation/windows.txt +++ b/documentation/windows.txt @@ -4,13 +4,15 @@ Windows sub-package Dragonfly includes several toolkits for non-speech user interfaces. These include for example, cross-platform generic window control, access to -monitor information and access to the system clipboard. +monitor information, simple geometry helpers and access to the system +clipboard. Contents of Dragonfly's windows sub-package: .. toctree:: :maxdepth: 2 + geometry_classes clipboard monitor_classes window_classes diff --git a/dragonfly/language/base/digits.py b/dragonfly/language/base/digits.py index 8c481d1b..335fb857 100644 --- a/dragonfly/language/base/digits.py +++ b/dragonfly/language/base/digits.py @@ -33,6 +33,12 @@ # Base class for digit-series element classes. class Digits(Repetition): + """ + Language-aware element for a spoken series of digits. + + The recognized value can be returned either as a list of digit values or + combined into an integer via the ``as_int`` argument. + """ _content = None _digit_name = "_digit" @@ -92,6 +98,7 @@ def value(self, node): # Digits reference class. class DigitsRef(RuleWrap): + """Named rule wrapper around :class:`Digits` for use in rule extras.""" def __init__(self, name=None, min=1, max=12, as_int=True, default=None): element = Digits(name=None, min=min, max=max, as_int=as_int) diff --git a/dragonfly/language/base/integer.py b/dragonfly/language/base/integer.py index a0e9f49b..d5d5f507 100644 --- a/dragonfly/language/base/integer.py +++ b/dragonfly/language/base/integer.py @@ -34,6 +34,13 @@ # Base class for integer element classes. class Integer(Alternative): + """ + Language-aware element for spoken integers within a numeric range. + + The active speech recognition engine language determines which spoken + forms are available unless a specific content implementation is passed + explicitly. + """ _content = None @@ -90,12 +97,19 @@ def _build_children(self, min, max): # Integer reference class. class IntegerRef(RuleWrap): + """Named rule wrapper around :class:`Integer` for use in rule extras.""" def __init__(self, name, min, max, default=None): element = Integer(None, min, max) RuleWrap.__init__(self, name, element, default=default) class ShortIntegerRef(RuleWrap): + """ + Variant of :class:`IntegerRef` that accepts shorter spoken forms. + + This uses language-specific short-number content when available and + otherwise falls back to the standard integer content for the language. + """ def __init__(self, name, min, max, default=None): element = Integer(None, min, max, content=language.ShortIntegerContent) diff --git a/dragonfly/language/base/number.py b/dragonfly/language/base/number.py index a6a17124..1992e956 100644 --- a/dragonfly/language/base/number.py +++ b/dragonfly/language/base/number.py @@ -34,6 +34,13 @@ # Number class. class Number(Alternative): + """ + Language-aware element for spoken whole numbers and number series. + + This combines the current language's integer content into a higher-level + element that can interpret a single number or a spoken series of smaller + numbers as one value. + """ _int_max = 1000000 _ser_len = 8 @@ -81,6 +88,7 @@ def value(self, node): # Number reference class. class NumberRef(RuleWrap): + """Named rule wrapper around :class:`Number` for use in rule extras.""" def __init__(self, name=None, zero=False, default=None): element = Number(None, zero=zero) diff --git a/dragonfly/windows/point.py b/dragonfly/windows/point.py index f10db552..fa21ef16 100644 --- a/dragonfly/windows/point.py +++ b/dragonfly/windows/point.py @@ -32,6 +32,12 @@ #=========================================================================== class Point(object): + """ + Two-dimensional point with floating-point coordinates. + + The class provides small geometry helpers used throughout Dragonfly's + window and monitor toolkits. + """ #----------------------------------------------------------------------- # Methods for initialization, copying, and introspection. diff --git a/dragonfly/windows/rectangle.py b/dragonfly/windows/rectangle.py index 4db7a477..1afbb645 100644 --- a/dragonfly/windows/rectangle.py +++ b/dragonfly/windows/rectangle.py @@ -30,6 +30,14 @@ # Rectangle class. class Rectangle(Point): + """ + Axis-aligned rectangle represented by an origin point and size. + + Rectangle inherits the position handling from + :class:`~dragonfly.windows.point.Point` and adds width, height, + centre-point, and containment helpers used by the window and monitor + APIs. + """ #----------------------------------------------------------------------- # Methods for initialization, copying, and introspection. From e0be5cdb42bc835dd5957c9e36279f82b45639df Mon Sep 17 00:00:00 2001 From: Kendon Bell Date: Sat, 21 Mar 2026 20:35:01 +1300 Subject: [PATCH 2/2] Refine windows documentation summary --- documentation/windows.txt | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/documentation/windows.txt b/documentation/windows.txt index c94ba1e5..c53a37c9 100644 --- a/documentation/windows.txt +++ b/documentation/windows.txt @@ -4,8 +4,7 @@ Windows sub-package Dragonfly includes several toolkits for non-speech user interfaces. These include for example, cross-platform generic window control, access to -monitor information, simple geometry helpers and access to the system -clipboard. +monitor information and access to the system clipboard. Contents of Dragonfly's windows sub-package: