Merge pull request #1854 from rmartin16/docs

Implement documentation linting

.readthedocs.yaml

@@ -7,9 +7,12 @@ version: 2
 
 # Set the version of Python and other tools you might need
 build:
-  os: ubuntu-20.04
+  os: ubuntu-22.04
   tools:
-    python: "3.9"
+    python: "3"
+  jobs:
+    pre_build:
+      - tox -e docs-lint
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
@@ -27,4 +30,5 @@ python:
   - method: pip
     path: core
     extra_requirements:
-    - docs
+      - docs
+      - dev

android/src/toga_android/widgets/internal/pickers.py

@@ -1,4 +1,4 @@
-from abc import ABC, abstractclassmethod
+from abc import ABC, abstractmethod
 
 from ...libs.android.view import OnClickListener, View__MeasureSpec
 from ...libs.android.widget import EditText
@@ -15,11 +15,13 @@ def onClick(self, _):
 
 
 class PickerBase(Widget, ABC):
-    @abstractclassmethod
+    @classmethod
+    @abstractmethod
     def _get_icon(cls):
         raise NotImplementedError
 
-    @abstractclassmethod
+    @classmethod
+    @abstractmethod
     def _get_hint(cls):
         raise NotImplementedError
 

android/src/toga_android/window.py

@@ -79,7 +79,7 @@ def set_title(self, title):
         self.app.native.setTitle(title)
 
     def get_position(self):
-        return (0, 0)
+        return 0, 0
 
     def set_position(self, position):
         # Does nothing on mobile
@@ -103,7 +103,7 @@ def hide(self):
         pass
 
     def get_visible(self):
-        # The window is alays visible
+        # The window is always visible
         return True
 
     def close(self):

changes/1854.misc.rst

@@ -0,0 +1 @@
+New ``tox`` environments were added for documentation linting and rebuilding as well as running linting prior to RTD CI builds.

cocoa/src/toga_cocoa/app.py

@@ -385,7 +385,7 @@ def enter_full_screen(self, windows):
             window.content._impl.native.enterFullScreenMode(screen, withOptions=opts)
             # Going full screen causes the window content to be re-homed
             # in a NSFullScreenWindow; teach the new parent window
-            # about it's Toga representations.
+            # about its Toga representations.
             window.content._impl.native.window._impl = window._impl
             window.content._impl.native.window.interface = window
 

cocoa/src/toga_cocoa/keys.py

@@ -213,4 +213,4 @@ def cocoa_key(shortcut):
             key = key.replace(mod.value, "")
             modifiers |= mask
 
-    return (key, modifiers)
+    return key, modifiers

cocoa/src/toga_cocoa/libs/core_graphics.py

@@ -208,8 +208,6 @@ class CGEventRef(c_void_p):
 kCGImageAlphaNoneSkipFirst = 6
 kCGImageAlphaOnly = 7
 
-kCGImageAlphaPremultipliedLast = 1
-
 kCGBitmapAlphaInfoMask = 0x1F
 kCGBitmapFloatComponents = 1 << 8
 

cocoa/src/toga_cocoa/widgets/base.py

@@ -102,7 +102,7 @@ def set_tab_index(self, tab_index):
 
     def add_child(self, child):
         if self.viewport:
-            # we are the the top level NSView
+            # we are the top level NSView
             child.container = self
         else:
             child.container = self.container

cocoa/src/toga_cocoa/widgets/optioncontainer.py

@@ -13,7 +13,7 @@ class TogaTabViewDelegate(NSObject):
     def tabView_didSelectTabViewItem_(self, view, item) -> None:
         # If the widget is part of a visible layout, and a resize event has
         # occurred while the tab wasn't visible, the layout of *this* tab won't
-        # reflect the new availalble size. Refresh the layout.
+        # reflect the new available size. Refresh the layout.
         if self.interface.window:
             self.interface.refresh()
 
@@ -35,7 +35,7 @@ def create(self):
 
         # Cocoa doesn't provide an explicit (public) API for tracking
         # tab enabled/disabled status; it's handled by the delegate returning
-        # if a specific tab should be enabled/disabled. Keep the set set of
+        # if a specific tab should be enabled/disabled. Keep the set of
         # currently disabled tabs for reference purposes.
         self._disabled_tabs = set()
 

cocoa/src/toga_cocoa/widgets/slider.py

@@ -60,7 +60,7 @@ def set_value(self, value):
         self.native.doubleValue = value
 
     def get_range(self):
-        return (self.native.minValue, self.native.maxValue)
+        return self.native.minValue, self.native.maxValue
 
     def set_range(self, range):
         self.native.minValue = range[0]

cocoa/src/toga_cocoa/window.py

@@ -77,7 +77,7 @@ def windowDidResize_(self, notification) -> None:
 
     @objc_method
     def toolbarAllowedItemIdentifiers_(self, toolbar):
-        "Determine the list of available toolbar items"
+        """Determine the list of available toolbar items"""
         # This method is required by the Cocoa API, but isn't actually invoked,
         # because customizable toolbars are no longer a thing.
         allowed = NSMutableArray.alloc().init()
@@ -87,7 +87,7 @@ def toolbarAllowedItemIdentifiers_(self, toolbar):
 
     @objc_method
     def toolbarDefaultItemIdentifiers_(self, toolbar):
-        "Determine the list of toolbar items that will display by default"
+        """Determine the list of toolbar items that will display by default"""
         default = NSMutableArray.alloc().init()
         for item in self.interface.toolbar:
             default.addObject_(toolbar_identifier(item))
@@ -97,7 +97,7 @@ def toolbarDefaultItemIdentifiers_(self, toolbar):
     def toolbar_itemForItemIdentifier_willBeInsertedIntoToolbar_(
         self, toolbar, identifier, insert: bool
     ):
-        "Create the requested toolbar button"
+        """Create the requested toolbar button"""
         native = NSToolbarItem.alloc().initWithItemIdentifier_(identifier)
         try:
             item = self.impl._toolbar_items[str(identifier)]
@@ -124,7 +124,7 @@ def toolbar_itemForItemIdentifier_willBeInsertedIntoToolbar_(
 
     @objc_method
     def validateToolbarItem_(self, item) -> bool:
-        "Confirm if the toolbar item should be enabled"
+        """Confirm if the toolbar item should be enabled"""
         return self.impl._toolbar_items[str(item.itemIdentifier)].enabled
 
     ######################################################################
@@ -133,7 +133,7 @@ def validateToolbarItem_(self, item) -> bool:
 
     @objc_method
     def onToolbarButtonPress_(self, obj) -> None:
-        "Invoke the action tied to the toolbar button"
+        """Invoke the action tied to the toolbar button"""
         item = self.impl._toolbar_items[str(obj.itemIdentifier)]
         item.action(obj)
 
@@ -198,7 +198,7 @@ def clear_content(self):
                 child._impl.container = None
 
     def set_content(self, widget):
-        # Set the window's view to the be the widget's native object.
+        # Set the window's view to be the widget's native object.
         self.native.contentView = widget.native
 
         # Set the widget's viewport to be based on the window's content.
@@ -211,8 +211,8 @@ def set_content(self, widget):
         # Enforce a minimum size based on the content size.
         # This is enforcing the *minimum* size; the window might actually be
         # bigger. If the window is resizable, using >= allows the window to
-        # be dragged larged; if not resizable, it enforces the smallest
-        # size that can be programmattically set on the window.
+        # be dragged larger; if not resizable, it enforces the smallest
+        # size that can be programmatically set on the window.
         self._min_width_constraint = NSLayoutConstraint.constraintWithItem_attribute_relatedBy_toItem_attribute_multiplier_constant_(  # noqa: E501
             widget.native,
             NSLayoutAttributeRight,
@@ -244,7 +244,7 @@ def set_title(self, title):
     def get_position(self):
         # If there is no active screen, we can't get a position
         if len(NSScreen.screens) == 0:
-            return (0, 0)
+            return 0, 0
 
         # The "primary" screen has index 0 and origin (0, 0).
         primary_screen = NSScreen.screens[0].frame
@@ -275,7 +275,7 @@ def set_position(self, position):
 
     def get_size(self):
         frame = self.native.frame
-        return (frame.size.width, frame.size.height)
+        return frame.size.width, frame.size.height
 
     def set_size(self, size):
         frame = self.native.frame

core/src/toga/app.py

@@ -16,7 +16,7 @@
 try:
     from importlib import metadata as importlib_metadata
 except ImportError:
-    # Backwards compatibility - imporlib.metadata was added in Python 3.8
+    # Backwards compatibility - importlib.metadata was added in Python 3.8
     import importlib_metadata
 
 
@@ -131,7 +131,7 @@ class App:
 
     When you create an App you need to provide it a name, an id for uniqueness
     (by convention, the identifier is a reversed domain name.) and an
-    optional startup function which should run once the App has initialised.
+    optional startup function which should run once the App has initialized.
     The startup function typically constructs some initial user interface.
 
     If the name and app_id are *not* provided, the application will attempt
@@ -151,7 +151,7 @@ class App:
     :param formal_name: The formal name of the application. Will be derived from
         packaging metadata if not provided.
     :param app_id: The unique application identifier. This will usually be a
-        reversed domain name, e.g. 'org.beeware.myapp'. Will be derived from
+        reversed domain name, e.g. ``org.beeware.myapp``. Will be derived from
         packaging metadata if not provided.
     :param app_name: The name of the Python module containing the app.
         Will be derived from the module defining the instance of the App class
@@ -163,16 +163,16 @@ class App:
         provided.
     :param version: The version number of the app. Will be derived from
         packaging metadata if not provided.
-    :param home_page: A URL for a home page for the app. Used in autogenerated
+    :param home_page: A URL for a home page for the app. Used in auto-generated
         help menu items. Will be derived from packaging metadata if not
         provided.
     :param description: A brief (one line) description of the app. Will be
         derived from packaging metadata if not provided.
     :param startup: The callback method before starting the app, typically to
         add the components. Must be a ``callable`` that expects a single
-        argument of :class:`~toga.App`.
-    :param windows: An iterable with objects of :class:`~toga.Window` that will
-        be the app's secondary windows.
+        argument of :class:`~toga.app.App`.
+    :param windows: An iterable with objects of :class:`~toga.window.Window`
+        that will be the app's secondary windows.
     """
 
     app = None
@@ -242,7 +242,7 @@ def __init__(
             if self._app_name is None and app_id:
                 self._app_name = app_id.split(".")[-1]
 
-        # Load the app metdata (if it is available)
+        # Load the app metadata (if it is available)
         # Apps packaged with Briefcase will have this metadata.
         try:
             self.metadata = importlib_metadata.metadata(self.module_name)
@@ -279,7 +279,7 @@ def __init__(
             raise RuntimeError("Toga application must have a formal name")
 
         # If an app_id has been provided, use it; otherwise, look to
-        # the module metadata. However, an app_id *must* be provied
+        # the module metadata. However, an app_id *must* be provided
         if app_id:
             self._app_id = app_id
         else:
@@ -390,7 +390,7 @@ def module_name(self):
     def app_id(self):
         """The identifier for the app.
 
-        This is a reversed domain name, often used for targetting resources,
+        This is a reversed domain name, often used for targeting resources,
         etc.
 
         :returns: The identifier as a ``str``.
@@ -409,7 +409,7 @@ def author(self):
     def version(self):
         """The version number of the app.
 
-        :returns: The version numberof the app, as a ``str``.
+        :returns: The version number of the app, as a ``str``.
         """
         return self._version
 

core/src/toga/command.py

@@ -5,7 +5,7 @@
 from toga.platform import get_platform_factory
 
 # BACKWARDS COMPATIBILITY: a token object that can be used to differentiate
-# between an explicitly provided ``None``, and a unspecified value falling
+# between an explicitly provided ``None``, and an unspecified value falling
 # back to a default.
 NOT_PROVIDED = object()
 
@@ -125,15 +125,15 @@ def __repr__(self):
 
     @property
     def key(self):
-        "A unique tuple describing the path to this group"
+        """A unique tuple describing the path to this group"""
         self_tuple = (self.section, self.order, self.text)
         if self.parent is None:
             return tuple([self_tuple])
         return tuple([*self.parent.key, self_tuple])
 
     @property
     def path(self):
-        "A list containing the chain of groups that contain this group"
+        """A list containing the chain of groups that contain this group"""
         if self.parent is None:
             return [self]
         return [*self.parent.path, self]
@@ -267,7 +267,7 @@ def __init__(
 
     @property
     def key(self):
-        "A unique tuple describing the path to this command"
+        """A unique tuple describing the path to this command"""
         return tuple([*self.group.key, (self.section, self.order, self.text)])
 
     def bind(self, factory=None):

core/src/toga/fonts.py

@@ -42,12 +42,12 @@ def measure(self, text, dpi, tight=False):
 
     @staticmethod
     def register(family, path, weight=NORMAL, style=NORMAL, variant=NORMAL):
-        """Registers a file-based font with it's family name, style, variant
+        """Registers a file-based font with its family name, style, variant
         and weight. When invalid values for style, variant or weight are
-        passed, NORMAL will be used.
+        passed, ``NORMAL`` will be used.
 
-        When a font file includes multiple font weight/style/etc, each variant
-        must be registerered separately:
+        When a font file includes multiple font weight/style/etc., each variant
+        must be registered separately::
 
             # Register a simple regular font
             Font.register("Font Awesome 5 Free Solid", "resources/Font Awesome 5 Free-Solid-900.otf")
@@ -60,16 +60,12 @@ def register(family, path, weight=NORMAL, style=NORMAL, variant=NORMAL):
             Font.register("Bahnschrift", "resources/Bahnschrift.ttf")
             Font.register("Bahnschrift", "resources/Bahnschrift.ttf", weight=Font.BOLD)
 
-        Args:
-            family (str): The font family name. This is the name that can be
+        :param family: The font family name. This is the name that can be
                 referenced in style definitions.
-            path (str): The path to the font file.
-            weight (str): The font weight: Font.NORMAL (default) or a value
-                from Font.FONT_WEIGHTS
-            style (str): The font style: Font.NORMAL (default) or a value from
-                Font.FONT_STYLES
-            variant (str): The font variant: Font.NORMAL (default) or a value
-                from Font.FONT_VARIANTS
+        :param path: The path to the font file.
+        :param weight: The font weight. Default value is ``NORMAL``.
+        :param style: The font style. Default value is ``NORMAL``.
+        :param variant: The font variant. Default value is ``NORMAL``.
         """
         font_key = Font.registered_font_key(
             family, weight=weight, style=style, variant=variant
@@ -80,17 +76,15 @@ def register(family, path, weight=NORMAL, style=NORMAL, variant=NORMAL):
     def registered_font_key(family, weight, style, variant):
         """Creates a key for storing a registered font in the font cache.
 
-        If weight, style or variant contain an invalid value, Font.NORMAL is
+        If weight, style or variant contain an invalid value, ``NORMAL`` is
         used instead.
 
-        Args:
-            family (str):  The font family name
-            weight (str):  The font weight: Font.NORMAL (default) or a value from Font.FONT_WEIGHTS
-            style (str):   The font style: Font.NORMAL (default) or a value from Font.FONT_STYLES
-            variant (str): The font variant: Font.NORMAL (default) or a value from Font.FONT_VARIANTS
-
-        Returns:
-            The font key (str)
+        :param family: The font family name. This is the name that can be
+            referenced in style definitions.
+        :param weight: The font weight. Default value is ``NORMAL``.
+        :param style: The font style. Default value is ``NORMAL``.
+        :param variant: The font variant. Default value is ``NORMAL``.
+        :returns: The font key
         """
         if weight not in constants.FONT_WEIGHTS:
             weight = NORMAL
@@ -99,4 +93,4 @@ def registered_font_key(family, weight, style, variant):
         if variant not in constants.FONT_VARIANTS:
             variant = NORMAL
 
-        return (family, weight, style, variant)
+        return family, weight, style, variant