Document remaining language and geometry APIs

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:

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):**
 

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

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 <https://app.gitter.im/#/room/#dragonfly2:matrix.org>`__
-  (also `bridged to Matrix <https://matrix.to/#/#dragonfly2:matrix.org>`__)
-  --- Real-time chat and historical discussions about Dragonfly
+   (also `bridged to Matrix <https://matrix.to/#/#dragonfly2:matrix.org>`__)
+   --- Real-time chat and historical discussions about Dragonfly
 
  * `Dragonfly Speech Google Group
    <https://groups.google.com/forum/#!forum/dragonflyspeech>`_

documentation/windows.txt

@@ -11,6 +11,7 @@ Contents of Dragonfly's windows sub-package:
 .. toctree::
    :maxdepth: 2
 
+   geometry_classes
    clipboard
    monitor_classes
    window_classes

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)

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)

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)

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.

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.