Improve documentation for pyface.action and pyface.tasks.action submodules

pyface/action/action_event.py

@@ -31,7 +31,7 @@ class ActionEvent(HasTraits):
     def __init__(self, **traits):
         """ Creates a new action event.
 
-        Note: Every keyword argument becoames a public attribute of the event.
+        Note: Every keyword argument becomes a public attribute of the event.
         """
         # Base-class constructor.
         super(ActionEvent, self).__init__(**traits)

pyface/action/api.py

@@ -9,6 +9,63 @@
 # Thanks for using Enthought open source!
 
 
+"""
+
+API for the ``pyface.action`` subpackage.
+
+Actions
+-------
+
+- :class:`~.Action`
+- :class:`~.FieldAction`
+- :class:`~.GUIApplicationAction`
+- :class:`~.ListeningAction`
+- :class:`~.TraitsUIWidgetAction`
+- :class:`~.WindowAction`
+
+Action Controller
+-----------------
+
+- :class:`~.ActionController`
+
+Action Event
+------------
+
+- :class:`~.ActionEvent`
+
+Action Managers
+---------------
+
+- :class:`~.ActionManager`
+- ``MenuManager``
+- ``MenuBarManager``
+- ``StatusBarManager``
+- ``ToolBarManager``
+- ``ToolPaletteManager``, only for the Wx toolkit.
+
+Action Manager Items
+--------------------
+
+- :class:`~.ActionManagerItem`
+- :class:`~.ActionItem`
+
+Layout support
+--------------
+
+- :class:`~.Group`
+- :class:`~.Separator`
+
+Useful Application and Window actions
+-------------------------------------
+
+- :class:`~.AboutAction`
+- :class:`~.CloseActiveWindowAction`
+- :class:`~.CreateWindowAction`
+- :class:`~.ExitAction`
+- :class:`~.CloseWindowAction`
+
+"""
+
 from .action import Action
 from .action_controller import ActionController
 from .action_event import ActionEvent

pyface/action/field_action.py

@@ -18,7 +18,7 @@
 class FieldAction(Action):
     """ A widget action containing an IField
 
-    When the value in the field is changed, the `on_peform` method is called
+    When the value in the field is changed, the `on_perform` method is called
     with the new value as the argument.
     """
 

pyface/action/menu_bar_manager.py

@@ -8,7 +8,11 @@
 #
 # Thanks for using Enthought open source!
 
-""" A menu bar manager realizes itself in errr, a menu bar control. """
+""" A toolkit-specific menu bar manager that realizes itself in a menu bar
+control.
+
+- :attr:`~.MenuBarManager`
+"""
 
 
 # Import the toolkit specific version.

pyface/action/menu_manager.py

@@ -8,7 +8,10 @@
 #
 # Thanks for using Enthought open source!
 
-""" A menu manager realizes itself in a menu control. """
+""" A toolkit-specific menu manager that realizes itself in a menu control.
+
+- :attr:`~.MenuManager`
+"""
 
 
 # Import the toolkit specific version.

pyface/action/status_bar_manager.py

@@ -8,7 +8,11 @@
 #
 # Thanks for using Enthought open source!
 
-""" A status bar manager realizes itself in a status bar control. """
+""" A toolkit-specific status bar manager that realizes itself in a status bar
+control.
+
+- :attr:`~.StatusBarManager`
+"""
 
 
 # Import the toolkit specific version.

pyface/action/tool_bar_manager.py

@@ -8,7 +8,11 @@
 #
 # Thanks for using Enthought open source!
 
-""" A tool bar manager realizes itself in a tool bar control. """
+""" A toolkit-specific tool bar manager that realizes itself in a tool bar
+control.
+
+- :attr:`~.ToolBarManager`
+"""
 
 
 # Import the toolkit specific version.

pyface/action/tool_palette_manager.py

@@ -8,7 +8,11 @@
 #
 # Thanks for using Enthought open source!
 
-""" A tool bar manager realizes itself in a tool palette control. """
+""" A toolkit-specific tool bar manager that realizes itself in a tool palette
+control.
+
+- :attr:`~.ToolPaletteManager`
+"""
 
 
 # Import the toolkit specific version.

pyface/tasks/action/api.py

@@ -8,6 +8,57 @@
 #
 # Thanks for using Enthought open source!
 
+"""
+
+API for the ``pyface.tasks.action`` subpackage.
+
+ActionSchemas and aliases
+-------------------------
+
+- :class:`~.ActionSchema`
+- :class:`~.GroupSchema`
+- :class:`~.MenuSchema`
+- :class:`~.MenuBarSchema`
+- :class:`~.ToolBarSchema`
+- :attr:`~.SGroup`
+- :attr:`~.SMenu`
+- :attr:`~.SMenuBar`
+- :attr:`~.SToolBar`
+
+Schema Addition
+---------------
+
+- :class:`~.SchemaAddition`
+
+Tasks-specific Action Controller
+--------------------------------
+
+- :class:`~.TaskActionController`
+
+Tasks-specific Action Manager factory
+-------------------------------------
+
+- :class:`~.TaskActionManagerBuilder`
+
+Tasks-specific Actions
+----------------------
+
+- :class:`~.CentralPaneAction`
+- :class:`~.DockPaneAction`
+- :class:`~.EditorAction`
+- :class:`~.TaskAction`
+- :class:`~.TaskWindowAction`
+- :class:`~.TasksApplicationAction`
+
+Useful Tasks Actions and Groups
+-------------------------------
+
+- :class:`~.DockPaneToggleGroup`
+- :class:`~.TaskToggleGroup`
+- :class:`~.TaskWindowToggleGroup`
+- :class:`~.CreateTaskWindowAction`
+
+"""
 
 from .dock_pane_toggle_group import DockPaneToggleGroup
 from .schema import (

pyface/tasks/action/listening_action.py

@@ -7,6 +7,9 @@
 # is also available online at http://www.enthought.com/licenses/BSD.txt
 #
 # Thanks for using Enthought open source!
-# Backward compatibility import
+
+""" This module exists purely for backwards compatibility.
+Please use :class:`pyface.action.listening_action.ListeningAction` instead.
+"""
 
 from pyface.action.listening_action import ListeningAction

pyface/tasks/action/schema.py

@@ -48,14 +48,14 @@ class Schema(HasTraits):
     """ The abstract base class for all Tasks action schemas.
     """
 
-    # The schema's identifier (unique within its parent schema).
+    #: The schema's identifier (unique within its parent schema).
     id = Str()
 
     def _id_default(self):
         return get_unique_id(self)
 
-    # The list of sub-items in the schema. These items can be other
-    # (non-top-level) schema or concrete instances from the Pyface API.
+    #: The list of sub-items in the schema. These items can be other
+    #: (non-top-level) schema or concrete instances from the Pyface API.
     items = List(SubSchema)
 
     def __init__(self, *items, **traits):
@@ -103,10 +103,10 @@ class GroupSchema(Schema):
     """ A schema for a Pyface Group.
     """
 
-    # A factory for instantiating a pyface Group.
+    #: A factory for instantiating a pyface Group.
     group_factory = Callable(Group)
 
-    # Does the group require a separator when it is visualized?
+    #: Does the group require a separator when it is visualized?
     separator = Bool(True)
 
     def create(self, children):
@@ -118,16 +118,16 @@ class MenuSchema(Schema):
     """ A schema for a Pyface MenuManager.
     """
 
-    # The menu's user visible name.
+    #: The menu's user visible name.
     name = Str()
 
-    # Does the menu require a separator before the menu item?
+    #: Does the menu require a separator before the menu item?
     separator = Bool(False)
 
-    # The default action for tool button when shown in a toolbar (Qt only)
+    #: The default action for tool button when shown in a toolbar (Qt only)
     action = Instance(Action)
 
-    # A factory for instantiating a pyface MenuManager.
+    #: A factory for instantiating a pyface MenuManager.
     menu_manager_factory = Callable(MenuManager)
 
     def create(self, children):
@@ -141,10 +141,10 @@ class MenuBarSchema(Schema):
     """ A schema for a Pyface MenuBarManager.
     """
 
-    # Assign a default ID for menu bar schemas.
+    #: Assign a default ID for menu bar schemas.
     id = "MenuBar"
 
-    # A factory for instantiating a pyface MenuBarManager.
+    #: A factory for instantiating a pyface MenuBarManager.
     menu_bar_manager_factory = Callable(MenuBarManager)
 
     def create(self, children):
@@ -156,26 +156,26 @@ class ToolBarSchema(Schema):
     """ A schema for a Pyface ToolBarManager.
     """
 
-    # Assign a default ID for tool bar schemas.
+    #: Assign a default ID for tool bar schemas.
     id = "ToolBar"
 
-    # The tool bar's user visible name. Note that this name may not be used on
-    # all platforms.
+    #: The tool bar's user visible name. Note that this name may not be used on
+    #: all platforms.
     name = Str("Tool Bar")
 
-    # The size of tool images (width, height).
+    #: The size of tool images (width, height).
     image_size = Tuple((16, 16))
 
-    # The orientation of the toolbar.
+    #: The orientation of the toolbar.
     orientation = Enum("horizontal", "vertical")
 
-    # Should we display the horizontal divider?
+    #: Should we display the horizontal divider?
     show_divider = Bool(True)
 
-    # Should we display the name of each tool bar tool under its image?
+    #: Should we display the name of each tool bar tool under its image?
     show_tool_names = Bool(True)
 
-    # A factory for instantiating a pyface ToolBarManager
+    #: A factory for instantiating a pyface ToolBarManager
     tool_bar_manager_factory = Callable(ToolBarManager)
 
     def create(self, children):

pyface/tasks/action/schema_addition.py

@@ -15,41 +15,42 @@ class SchemaAddition(HasTraits):
     """ An addition to an existing menu bar or tool bar schema.
     """
 
-    # The schema addition's identifier. This optional, but if left unspecified,
-    # other schema additions will be unable to refer to this one.
+    #: The schema addition's identifier. This optional, but if left
+    #: unspecified, other schema additions will be unable to refer to this one.
     id = Str()
 
-    # A callable to create the item. Should have the following signature:
-    #    callable() -> Action | ActionItem | Group | MenuManager |
-    #                  GroupSchema | MenuSchema
-    # If the result is a schema, it will itself admit of extension by other
-    # additions. If not, the result will be fixed.
+    #: A callable to create the item. Should have the following signature:
+    #:    callable() -> Action | ActionItem | Group | MenuManager |
+    #:                  GroupSchema | MenuSchema
+    #:
+    #: If the result is a schema, it will itself admit of extension by other
+    #: additions. If not, the result will be fixed.
     factory = Callable
 
-    # A forward-slash-separated path through the action hierarchy to the menu
-    # to add the action, group or menu to. For example:
-    # - To add an item to the menu bar: ``path = "MenuBar"``
-    # - To add an item to the tool bar: ``path = "ToolBar"``
-    # - To add an item to a sub-menu: ``path = "MenuBar/File/New"``
+    #: A forward-slash-separated path through the action hierarchy to the menu
+    #: to add the action, group or menu to. For example:
+    #: - To add an item to the menu bar: ``path = "MenuBar"``
+    #: - To add an item to the tool bar: ``path = "ToolBar"``
+    #: - To add an item to a sub-menu: ``path = "MenuBar/File/New"``
     path = Str()
 
-    # The item appears after the item with this ID.
-    # - for groups, this is the ID of another group.
-    # - for menus and actions, this is the ID of another menu or action.
+    #: The item appears after the item with this ID.
+    #: - for groups, this is the ID of another group.
+    #: - for menus and actions, this is the ID of another menu or action.
     after = Str()
 
-    # The action appears before the item with this ID.
-    # - for groups, this is the ID of another group.
-    # - for menus and actions, this is the ID of another menu or action.
+    #: The action appears before the item with this ID.
+    #: - for groups, this is the ID of another group.
+    #: - for menus and actions, this is the ID of another menu or action.
     before = Str()
 
-    # The action appears at the absolute specified position first or last.
-    # This is useful for example to keep the File menu the first menu in a
-    # menubar, the help menu the last etc.
-    # If multiple actions in a schema have absolute_position 'first', they
-    # will appear in the same order specified; unless 'before' and 'after'
-    # traits are set to sort these multiple items.
-    # This trait takes precedence over 'after' and 'before', and values of
-    # those traits that are not compatible with the  absolute_position are
-    # ignored.
+    #: The action appears at the absolute specified position first or last.
+    #: This is useful for example to keep the File menu the first menu in a
+    #: menubar, the help menu the last etc.
+    #: If multiple actions in a schema have absolute_position 'first', they
+    #: will appear in the same order specified; unless 'before' and 'after'
+    #: traits are set to sort these multiple items.
+    #: This trait takes precedence over 'after' and 'before', and values of
+    #: those traits that are not compatible with the  absolute_position are
+    #: ignored.
     absolute_position = Enum(None, "first", "last")