diff --git a/chaco/abstract_data_range.py b/chaco/abstract_data_range.py index d880f4ee9..9420fb084 100644 --- a/chaco/abstract_data_range.py +++ b/chaco/abstract_data_range.py @@ -15,30 +15,30 @@ class AbstractDataRange(HasTraits): They support "autoscaling" by querying their associated data sources. """ - # The list of data sources to which this range responds. + #: The list of data sources to which this range responds. sources = List(Instance(AbstractDataSource)) - # The actual value of the lower bound of this range. To set it, use - # low_setting. (Setting this attribute directly just calls the setter for - # low_setting.) Although the default value is specified as 0.0, subclasses - # can redefine the default. Also, subclasses can redefined the type to - # correspond to their dimensionality. + #: The actual value of the lower bound of this range. To set it, use + #: low_setting. (Setting this attribute directly just calls the setter for + #: low_setting.) Although the default value is specified as 0.0, subclasses + #: can redefine the default. Also, subclasses can redefined the type to + #: correspond to their dimensionality. low = Float(0.0) - # The actual value of the upper bound of this range. To set it, use - # high_setting. (Setting this attribute directly just calls the setter for - # high_setting.) Although the default value is specified as 1.0, subclasses - # can redefine the default. Also, subclasses can redefined the type to - # correspond to their dimensionality. + #: The actual value of the upper bound of this range. To set it, use + #: high_setting. (Setting this attribute directly just calls the setter for + #: high_setting.) Although the default value is specified as 1.0, subclasses + #: can redefine the default. Also, subclasses can redefined the type to + #: correspond to their dimensionality. high = Float(1.0) - # Setting for the lower bound of this range. + #: Setting for the lower bound of this range. low_setting = Trait('auto', 'auto', Float) - # Setting for the upper bound of this range. + #: Setting for the upper bound of this range. high_setting = Trait('auto', 'auto', Float) - # Event that is fired when the actual bounds values change; the value - # of the event is a tuple (low_bound, high_bound) + #: Event that is fired when the actual bounds values change; the value + #: of the event is a tuple (low_bound, high_bound) updated = Event #------------------------------------------------------------------------ diff --git a/chaco/abstract_data_source.py b/chaco/abstract_data_source.py index 39db59333..b721ea3d5 100644 --- a/chaco/abstract_data_source.py +++ b/chaco/abstract_data_source.py @@ -22,34 +22,34 @@ class AbstractDataSource(HasTraits): possible, domain classes (or an adapter) must implement AbstractDataSource. """ - # The dimensionality of the value at each index point. - # Subclasses re-declare this trait as a read-only trait with - # the right default value. + #: The dimensionality of the value at each index point. + #: Subclasses re-declare this trait as a read-only trait with + #: the right default value. value_dimension = DimensionTrait - # The dimensionality of the indices into this data source. - # Subclasses re-declare this trait as a read-only trait with - # the right default value. + #: The dimensionality of the indices into this data source. + #: Subclasses re-declare this trait as a read-only trait with + #: the right default value. index_dimension = DimensionTrait - # A dictionary keyed on strings. In general, it maps to indices (or tuples - # of indices, depending on **value_dimension**), as in the case of - # selections and annotations. Applications and renderers can add their own - # custom metadata, but must avoid using keys that might result in name - # collision. + #: A dictionary keyed on strings. In general, it maps to indices (or tuples + #: of indices, depending on **value_dimension**), as in the case of + #: selections and annotations. Applications and renderers can add their own + #: custom metadata, but must avoid using keys that might result in name + #: collision. metadata = Dict - # Event that fires when the data values change. + #: Event that fires when the data values change. data_changed = Event - # Event that fires when just the bounds change. + #: Event that fires when just the bounds change. bounds_changed = Event - # Event that fires when metadata structure is changed. + #: Event that fires when metadata structure is changed. metadata_changed = Event - # Should the data that this datasource refers to be serialized when - # the datasource is serialized? + #: Should the data that this datasource refers to be serialized when + #: the datasource is serialized? persist_data = Bool(True) #------------------------------------------------------------------------ diff --git a/chaco/abstract_mapper.py b/chaco/abstract_mapper.py index bd4204d9d..8483bb741 100644 --- a/chaco/abstract_mapper.py +++ b/chaco/abstract_mapper.py @@ -12,16 +12,16 @@ class AbstractMapper(HasTraits): region in output space. """ - # A generic "update" event that generally means that anything that relies - # on this mapper for visual output should do a redraw or repaint. + #: A generic "update" event that generally means that anything that relies + #: on this mapper for visual output should do a redraw or repaint. updated = Event # FIXME: domain_limits is never used - # A tuple representing the minimum and maximum values of the domain (data - # space). The dimensionality of each value varies depending on the - # dimensions of the mapper, so for 1D mappers these will be scalars, for - # image and 2D mappers these will be tuples. + #: A tuple representing the minimum and maximum values of the domain (data + #: space). The dimensionality of each value varies depending on the + #: dimensions of the mapper, so for 1D mappers these will be scalars, for + #: image and 2D mappers these will be tuples. domain_limits = Tuple(None, None) def map_screen(self, data_array): diff --git a/chaco/abstract_overlay.py b/chaco/abstract_overlay.py index 64046ae60..7709886ab 100644 --- a/chaco/abstract_overlay.py +++ b/chaco/abstract_overlay.py @@ -19,15 +19,15 @@ class AbstractOverlay(PlotComponent): containment-ownership relationship. """ - # The component that this object overlays. This can be None. By default, if - # this object is called to draw(), it tries to render onto this component. + #: The component that this object overlays. This can be None. By default, if + #: this object is called to draw(), it tries to render onto this component. component = Instance(Component) - # The default layer that this component draws into. + #: The default layer that this component draws into. draw_layer = "overlay" - # The background color (overrides PlotComponent). - # Typically, an overlay does not render a background. + #: The background color (overrides PlotComponent). + #: Typically, an overlay does not render a background. bgcolor = "transparent" def __init__(self, component=None, *args, **kw): diff --git a/chaco/abstract_plot_data.py b/chaco/abstract_plot_data.py index 0321aeada..0b2611085 100644 --- a/chaco/abstract_plot_data.py +++ b/chaco/abstract_plot_data.py @@ -12,9 +12,9 @@ class AbstractPlotData(HasTraits): # Events that consumers of this data should use #------------------------------------------------------------------------- - # Indicates that some of the data has changed. The event object must - # be a dict with keys "added", "removed", "changed" and values that are - # lists of strings. This event is used by consumers of this data. + #: Indicates that some of the data has changed. The event object must + #: be a dict with keys "added", "removed", "changed" and values that are + #: lists of strings. This event is used by consumers of this data. data_changed = Event @@ -23,11 +23,11 @@ class AbstractPlotData(HasTraits): # interact with it. (Typically "consumers" just refers to Plots.) #------------------------------------------------------------------------- - # Can consumers (Plots) write data back through this interface using - # set_data()? + #: Can consumers (Plots) write data back through this interface using + #: set_data()? writable = Bool(True) - # Can consumers (Plots) set selections? + #: Can consumers (Plots) set selections? selectable = Bool(True) diff --git a/chaco/abstract_plot_renderer.py b/chaco/abstract_plot_renderer.py index c15a3cdd4..5ea0d639e 100644 --- a/chaco/abstract_plot_renderer.py +++ b/chaco/abstract_plot_renderer.py @@ -22,10 +22,10 @@ class AbstractPlotRenderer(PlotComponent): # Override default values of inherited traits PlotComponent #------------------------------------------------------------------------ - # Overrides the default value inherited from PlotComponent. + #: Overrides the default value inherited from PlotComponent. bgcolor = "transparent" - # Overrides the default value inherited from PlotComponent. + #: Overrides the default value inherited from PlotComponent. resizable = "hv" @@ -65,13 +65,14 @@ def map_index(self, screen_pt, threshold=0.0, outside_returns_none=True, \ Returns ------- - An index into the plot's index array(s). Typically this index is just - an integer, but if the plot has a 2-D index dimension, then this method - returns a tuple of integers. If the input point cannot be mapped to an - index, then None is returned. - - If *screen_pt* corresponds to multiple indices, then only the first - index is returned. + index : int + An index into the plot's index array(s). Typically this index is just + an integer, but if the plot has a 2-D index dimension, then this method + returns a tuple of integers. If the input point cannot be mapped to an + index, then None is returned. + + If *screen_pt* corresponds to multiple indices, then only the first + index is returned. """ raise NotImplementedError diff --git a/chaco/array_data_source.py b/chaco/array_data_source.py index 14340c6f7..1df4e1dbe 100644 --- a/chaco/array_data_source.py +++ b/chaco/array_data_source.py @@ -63,17 +63,17 @@ class ArrayDataSource(AbstractDataSource): # AbstractDataSource traits #------------------------------------------------------------------------ - # The dimensionality of the indices into this data source (overrides - # AbstractDataSource). + #: The dimensionality of the indices into this data source (overrides + #: AbstractDataSource). index_dimension = Constant('scalar') - # The dimensionality of the value at each index point (overrides - # AbstractDataSource). + #: The dimensionality of the value at each index point (overrides + #: AbstractDataSource). value_dimension = Constant('scalar') - # The sort order of the data. - # This is a specialized optimization for 1-D arrays, but it's an important - # one that's used everywhere. + #: The sort order of the data. + #: This is a specialized optimization for 1-D arrays, but it's an important + #: one that's used everywhere. sort_order = SortOrderTrait diff --git a/chaco/array_plot_data.py b/chaco/array_plot_data.py index 0dd04378d..1311c7f3f 100644 --- a/chaco/array_plot_data.py +++ b/chaco/array_plot_data.py @@ -24,14 +24,14 @@ class ArrayPlotData(AbstractPlotData): # Public traits #------------------------------------------------------------------------- - # Map of names to arrays. Although there is no restriction on the array - # dimensions, each array must correspond to a single plot item; that - # is, a single name must not map to a multi-dimensional array unless - # the array is being used for an image plot or for something that can handle - # multi-dimensional input data. + #: Map of names to arrays. Although there is no restriction on the array + #: dimensions, each array must correspond to a single plot item; that + #: is, a single name must not map to a multi-dimensional array unless + #: the array is being used for an image plot or for something that can handle + #: multi-dimensional input data. arrays = Dict - # Consumers can write data to this object (overrides AbstractPlotData). + #: Consumers can write data to this object (overrides AbstractPlotData). writable = True def __init__(self, *data, **kw): diff --git a/chaco/axis.py b/chaco/axis.py index aaffaf732..9ab53e17e 100644 --- a/chaco/axis.py +++ b/chaco/axis.py @@ -34,114 +34,114 @@ class PlotAxis(AbstractOverlay): the component. """ - # The mapper that drives this axis. + #: The mapper that drives this axis. mapper = Instance(AbstractMapper) - # Keep an origin for plots that aren't attached to a component + #: Keep an origin for plots that aren't attached to a component origin = Enum("bottom left", "top left", "bottom right", "top right") - # The text of the axis title. + #: The text of the axis title. title = Trait('', Str, Unicode) #May want to add PlotLabel option - # The font of the title. + #: The font of the title. title_font = KivaFont('modern 12') - # The spacing between the axis line and the title + #: The spacing between the axis line and the title title_spacing = Trait('auto', 'auto', Float) - # The color of the title. + #: The color of the title. title_color = ColorTrait("black") - # The angle of the title, in degrees, from horizontal line + #: The angle of the title, in degrees, from horizontal line title_angle = Float(0.) - # The thickness (in pixels) of each tick. + #: The thickness (in pixels) of each tick. tick_weight = Float(1.0) - # The color of the ticks. + #: The color of the ticks. tick_color = ColorTrait("black") - # The font of the tick labels. + #: The font of the tick labels. tick_label_font = KivaFont('modern 10') - # The color of the tick labels. + #: The color of the tick labels. tick_label_color = ColorTrait("black") - # The rotation of the tick labels. + #: The rotation of the tick labels. tick_label_rotate_angle = Float(0) - # Whether to align to corners or edges (corner is better for 45 degree rotation) + #: Whether to align to corners or edges (corner is better for 45 degree rotation) tick_label_alignment = Enum('edge', 'corner') - # The margin around the tick labels. + #: The margin around the tick labels. tick_label_margin = Int(2) - # The distance of the tick label from the axis. + #: The distance of the tick label from the axis. tick_label_offset = Float(8.) - # Whether the tick labels appear to the inside or the outside of the plot area + #: Whether the tick labels appear to the inside or the outside of the plot area tick_label_position = Enum("outside", "inside") - # A callable that is passed the numerical value of each tick label and - # that returns a string. + #: A callable that is passed the numerical value of each tick label and + #: that returns a string. tick_label_formatter = Callable(DEFAULT_TICK_FORMATTER) - # The number of pixels by which the ticks extend into the plot area. + #: The number of pixels by which the ticks extend into the plot area. tick_in = Int(5) - # The number of pixels by which the ticks extend into the label area. + #: The number of pixels by which the ticks extend into the label area. tick_out = Int(5) - # Are ticks visible at all? + #: Are ticks visible at all? tick_visible = Bool(True) - # The dataspace interval between ticks. + #: The dataspace interval between ticks. tick_interval = Trait('auto', 'auto', Float) - # A callable that implements the AbstractTickGenerator interface. + #: A callable that implements the AbstractTickGenerator interface. tick_generator = Instance(AbstractTickGenerator) - # The location of the axis relative to the plot. This determines where - # the axis title is located relative to the axis line. + #: The location of the axis relative to the plot. This determines where + #: the axis title is located relative to the axis line. orientation = Enum("top", "bottom", "left", "right") - # Is the axis line visible? + #: Is the axis line visible? axis_line_visible = Bool(True) - # The color of the axis line. + #: The color of the axis line. axis_line_color = ColorTrait("black") - # The line thickness (in pixels) of the axis line. + #: The line thickness (in pixels) of the axis line. axis_line_weight = Float(1.0) - # The dash style of the axis line. + #: The dash style of the axis line. axis_line_style = LineStyle('solid') - # A special version of the axis line that is more useful for geophysical - # plots. + #: A special version of the axis line that is more useful for geophysical + #: plots. small_haxis_style = Bool(False) - # Does the axis ensure that its end labels fall within its bounding area? + #: Does the axis ensure that its end labels fall within its bounding area? ensure_labels_bounded = Bool(False) - # Does the axis prevent the ticks from being rendered outside its bounds? - # This flag is off by default because the standard axis *does* render ticks - # that encroach on the plot area. + #: Does the axis prevent the ticks from being rendered outside its bounds? + #: This flag is off by default because the standard axis *does* render ticks + #: that encroach on the plot area. ensure_ticks_bounded = Bool(False) - # Fired when the axis's range bounds change. + #: Fired when the axis's range bounds change. updated = Event #------------------------------------------------------------------------ # Override default values of inherited traits #------------------------------------------------------------------------ - # Background color (overrides AbstractOverlay). Axes usually let the color of - # the container show through. + #: Background color (overrides AbstractOverlay). Axes usually let the color of + #: the container show through. bgcolor = ColorTrait("transparent") - # Dimensions that the axis is resizable in (overrides PlotComponent). - # Typically, axes are resizable in both dimensions. + #: Dimensions that the axis is resizable in (overrides PlotComponent). + #: Typically, axes are resizable in both dimensions. resizable = "hv" #------------------------------------------------------------------------ diff --git a/chaco/barplot.py b/chaco/barplot.py index 570d918eb..579e3a2fc 100644 --- a/chaco/barplot.py +++ b/chaco/barplot.py @@ -27,68 +27,68 @@ class BarPlot(AbstractPlotRenderer): """ A renderer for bar charts. """ - # The data source to use for the index coordinate. + #: The data source to use for the index coordinate. index = Instance(ArrayDataSource) - # The data source to use as value points. + #: The data source to use as value points. value = Instance(ArrayDataSource) - # The data source to use as "starting" values for bars (along value axis). - # For instance, if the values are [10, 20] and starting_value - # is [3, 7], BarPlot will plot two bars, one between 3 and 10, and - # one between 7 and 20 + #: The data source to use as "starting" values for bars (along value axis). + #: For instance, if the values are [10, 20] and starting_value + #: is [3, 7], BarPlot will plot two bars, one between 3 and 10, and + #: one between 7 and 20 starting_value = Instance(ArrayDataSource) - # Labels for the indices. + #: Labels for the indices. index_mapper = Instance(AbstractMapper) - # Labels for the values. + #: Labels for the values. value_mapper = Instance(AbstractMapper) - # The orientation of the index axis. + #: The orientation of the index axis. orientation = Enum("h", "v") - # The direction of the index axis with respect to the graphics context's - # direction. + #: The direction of the index axis with respect to the graphics context's + #: direction. index_direction = Enum("normal", "flipped") - # The direction of the value axis with respect to the graphics context's - # direction. + #: The direction of the value axis with respect to the graphics context's + #: direction. value_direction = Enum("normal", "flipped") - # Type of width used for bars: - # - # 'data' - # The width is in the units along the x-dimension of the data space. - # 'screen' - # The width uses a fixed width of pixels. + #: Type of width used for bars: + #: + #: 'data' + #: The width is in the units along the x-dimension of the data space. + #: 'screen' + #: The width uses a fixed width of pixels. bar_width_type = Enum("data", "screen") - # Width of the bars, in data or screen space (determined by - # **bar_width_type**). + #: Width of the bars, in data or screen space (determined by + #: **bar_width_type**). bar_width = Float(10) - # Round on rectangle dimensions? This is not strictly an "antialias", but - # it has the same effect through exact pixel drawing. + #: Round on rectangle dimensions? This is not strictly an "antialias", but + #: it has the same effect through exact pixel drawing. antialias = Bool(True) - # Width of the border of the bars. + #: Width of the border of the bars. line_width = Float(1.0) - # Color of the border of the bars. + #: Color of the border of the bars. line_color = black_color_trait - # Color to fill the bars. + #: Color to fill the bars. fill_color = black_color_trait - # The RGBA tuple for rendering lines. It is always a tuple of length 4. - # It has the same RGB values as line_color_, and its alpha value is the - # alpha value of self.line_color multiplied by self.alpha. + #: The RGBA tuple for rendering lines. It is always a tuple of length 4. + #: It has the same RGB values as line_color_, and its alpha value is the + #: alpha value of self.line_color multiplied by self.alpha. effective_line_color = Property(Tuple, depends_on=['line_color', 'alpha']) - # The RGBA tuple for rendering the fill. It is always a tuple of length 4. - # It has the same RGB values as fill_color_, and its alpha value is the - # alpha value of self.fill_color multiplied by self.alpha. + #: The RGBA tuple for rendering the fill. It is always a tuple of length 4. + #: It has the same RGB values as fill_color_, and its alpha value is the + #: alpha value of self.fill_color multiplied by self.alpha. effective_fill_color = Property(Tuple, depends_on=['fill_color', 'alpha']) - # Overall alpha value of the image. Ranges from 0.0 for transparent to 1.0 + #: Overall alpha value of the image. Ranges from 0.0 for transparent to 1.0 alpha = Range(0.0, 1.0, 1.0) @@ -97,23 +97,23 @@ class BarPlot(AbstractPlotRenderer): # Convenience properties that correspond to either index_mapper or # value_mapper, depending on the orientation of the plot. - # Corresponds to either **index_mapper** or **value_mapper**, depending on - # the orientation of the plot. + #: Corresponds to either **index_mapper** or **value_mapper**, depending on + #: the orientation of the plot. x_mapper = Property - # Corresponds to either **value_mapper** or **index_mapper**, depending on - # the orientation of the plot. + #: Corresponds to either **value_mapper** or **index_mapper**, depending on + #: the orientation of the plot. y_mapper = Property - # Corresponds to either **index_direction** or **value_direction**, - # depending on the orientation of the plot. + #: Corresponds to either **index_direction** or **value_direction**, + #: depending on the orientation of the plot. x_direction = Property - # Corresponds to either **value_direction** or **index_direction**, - # depending on the orientation of the plot + #: Corresponds to either **value_direction** or **index_direction**, + #: depending on the orientation of the plot y_direction = Property - # Convenience property for accessing the index data range. + #: Convenience property for accessing the index data range. index_range = Property - # Convenience property for accessing the value data range. + #: Convenience property for accessing the value data range. value_range = Property diff --git a/chaco/base_1d_mapper.py b/chaco/base_1d_mapper.py index b269a52ae..bfddf57a4 100644 --- a/chaco/base_1d_mapper.py +++ b/chaco/base_1d_mapper.py @@ -13,26 +13,26 @@ class Base1DMapper(AbstractMapper): region in output space. """ - # The data-space bounds of the mapper. + #: The data-space bounds of the mapper. range = Instance(DataRange1D) - # The screen space position of the lower bound of the data space. + #: The screen space position of the lower bound of the data space. low_pos = Float(0.0) - # The screen space position of the upper bound of the data space. + #: The screen space position of the upper bound of the data space. high_pos = Float(1.0) - # Convenience property to get low and high positions in one structure. - # Must be a tuple (low_pos, high_pos). + #: Convenience property to get low and high positions in one structure. + #: Must be a tuple (low_pos, high_pos). screen_bounds = Property - # Should the mapper stretch the dataspace when its screen space bounds are - # modified (default), or should it preserve the screen-to-data ratio and - # resize the data bounds? If the latter, it will only try to preserve - # the ratio if both screen and data space extents are non-zero. + #: Should the mapper stretch the dataspace when its screen space bounds are + #: modified (default), or should it preserve the screen-to-data ratio and + #: resize the data bounds? If the latter, it will only try to preserve + #: the ratio if both screen and data space extents are non-zero. stretch_data = Bool(True) - # The sign of the mapping: 1 if deltas match sign, -1 if opposite sign + #: The sign of the mapping: 1 if deltas match sign, -1 if opposite sign sign = Property # If the subclass uses a cache, _cache_valid is maintained to diff --git a/chaco/base_2d_plot.py b/chaco/base_2d_plot.py index c15fc117e..ecb25f6c8 100644 --- a/chaco/base_2d_plot.py +++ b/chaco/base_2d_plot.py @@ -22,57 +22,57 @@ class Base2DPlot(AbstractPlotRenderer): # Data-related traits #------------------------------------------------------------------------ - # The data source to use for the index coordinate. + #: The data source to use for the index coordinate. index = Instance(GridDataSource) - # The data source to use as value points. + #: The data source to use as value points. value = Instance(ImageData) - # Screen mapper for 2-D structured (gridded) index data. + #: Screen mapper for 2-D structured (gridded) index data. index_mapper = Instance(GridMapper) - # Convenience property for accessing the data range of the mapper. + #: Convenience property for accessing the data range of the mapper. index_range = Property - # Convenience property for accessing the plots labels. + #: Convenience property for accessing the plots labels. labels = Property - # The direction that the first array returned by self.index.get_data() - # maps to. - # - # * 'h': index maps to x-direction - # * 'v': index maps to y-direction + #: The direction that the first array returned by self.index.get_data() + #: maps to. + #: + #: * 'h': index maps to x-direction + #: * 'v': index maps to y-direction orientation = Enum("h", "v") - # Overrides PlotComponent; 2-D plots draw on the 'image' layer, - # underneath all decorations and annotations, and above only the background - # fill color. + #: Overrides PlotComponent; 2-D plots draw on the 'image' layer, + #: underneath all decorations and annotations, and above only the background + #: fill color. draw_layer = "image" - # Convenience property for accessing the x-direction mappers regardless - # of orientation. This provides compatibility with a number of tools. + #: Convenience property for accessing the x-direction mappers regardless + #: of orientation. This provides compatibility with a number of tools. x_mapper = Property - # Convenience property for accessing the y-direction mappers regardless - # of orientation. This provides compatibility with a number of tools. + #: Convenience property for accessing the y-direction mappers regardless + #: of orientation. This provides compatibility with a number of tools. y_mapper = Property - # Overall alpha value of the image. Ranges from 0.0 for transparent to 1.0 - # for full intensity. + #: Overall alpha value of the image. Ranges from 0.0 for transparent to 1.0 + #: for full intensity. alpha = Trait(1.0, Range(0.0, 1.0)) - # Event fired when the index data changes. Subclasses can listen for this - # event and take appropriate steps (except for requesting a redraw, which - # is done in this class). + #: Event fired when the index data changes. Subclasses can listen for this + #: event and take appropriate steps (except for requesting a redraw, which + #: is done in this class). index_data_changed = Event - # Event fired when the index mapper changes. Subclasses can listen for this - # event and take appropriate steps (except for requesting a redraw, which - # is done in this class). + #: Event fired when the index mapper changes. Subclasses can listen for this + #: event and take appropriate steps (except for requesting a redraw, which + #: is done in this class). index_mapper_changed = Event - # Event fired when the value data changes. Subclasses can listen for this - # event and take appropriate steps (except for requesting a redraw, which - # is done in this class). + #: Event fired when the value data changes. Subclasses can listen for this + #: event and take appropriate steps (except for requesting a redraw, which + #: is done in this class). value_data_changed = Event #------------------------------------------------------------------------ diff --git a/chaco/base_plot_container.py b/chaco/base_plot_container.py index c2fd15e2f..3588ed807 100644 --- a/chaco/base_plot_container.py +++ b/chaco/base_plot_container.py @@ -25,15 +25,15 @@ class BasePlotContainer(Container): the visual results will probably be incorrect. """ - # Redefine the container layers to name the main layer as "plot" instead - # of the Enable default of "mainlayer" + #: Redefine the container layers to name the main layer as "plot" instead + #: of the Enable default of "mainlayer" container_under_layers = Tuple("background", "image", "underlay", "plot") - #------------------------------------------------------------------------ - # Duplicate trait declarations from PlotComponent. We don't subclass - # PlotComponent to avoid MRO complications with trait handlers and property - # getters/setters. - #------------------------------------------------------------------------ + #:------------------------------------------------------------------------ + #: Duplicate trait declarations from PlotComponent. We don't subclass + #: PlotComponent to avoid MRO complications with trait handlers and property + #: getters/setters. + #:------------------------------------------------------------------------ draw_order = Instance(list, args=(DEFAULT_DRAWING_ORDER,)) draw_layer = Str("plot") @@ -42,11 +42,11 @@ class BasePlotContainer(Container): # Deprecated traits #------------------------------------------------------------------------ - # Deprecated flag to indicate that a component needed to do old-style - # drawing. Unused by any recent Chaco component. + #: Deprecated flag to indicate that a component needed to do old-style + #: drawing. Unused by any recent Chaco component. use_draw_order = Bool(True) - # Deprecated property for accessing the components in the container. + #: Deprecated property for accessing the components in the container. plot_components = Property def _get_plot_components(self): diff --git a/chaco/base_plot_frame.py b/chaco/base_plot_frame.py index 97b884ddf..24dc68fbc 100644 --- a/chaco/base_plot_frame.py +++ b/chaco/base_plot_frame.py @@ -29,20 +29,20 @@ class BasePlotFrame(Container, PlotComponent): This class will be removed some time in the near future. """ - # A named list of places/positions/"slots" on the frame where PlotComponents - # can place themselves. Subclasses must redefine this trait with the - # appropriate values. Note that by default, __getattr__ treats these - # slot names as attributes on the class so they can be directly accessed. - # This is a class attribute. + #: A named list of places/positions/"slots" on the frame where PlotComponents + #: can place themselves. Subclasses must redefine this trait with the + #: appropriate values. Note that by default, __getattr__ treats these + #: slot names as attributes on the class so they can be directly accessed. + #: This is a class attribute. slot_names = () - # Dimensions in which this frame can resize to fit its components. - # This is similar to the **resizable** trait on PlotComponent. Chaco - # plot frames use this attribute in preference to the Enable - # **auto_size** attribute (which is overridden to be False by default). + #: Dimensions in which this frame can resize to fit its components. + #: This is similar to the **resizable** trait on PlotComponent. Chaco + #: plot frames use this attribute in preference to the Enable + #: **auto_size** attribute (which is overridden to be False by default). fit_components = Enum("", "h", "v", "hv") - # Overrides the Enable auto_size trait (which will be deprecated in the future) + #: Overrides the Enable auto_size trait (which will be deprecated in the future) auto_size = False draw_order = DEFAULT_DRAWING_ORDER diff --git a/chaco/base_xy_plot.py b/chaco/base_xy_plot.py index 183931a4d..d4d5a4567 100644 --- a/chaco/base_xy_plot.py +++ b/chaco/base_xy_plot.py @@ -36,63 +36,63 @@ class BaseXYPlot(AbstractPlotRenderer): # Data-related traits #------------------------------------------------------------------------ - # The data source to use for the index coordinate. + #: The data source to use for the index coordinate. index = Instance(ArrayDataSource) - # The data source to use as value points. + #: The data source to use as value points. value = Instance(AbstractDataSource) - # Screen mapper for index data. + #: Screen mapper for index data. index_mapper = Instance(AbstractMapper) - # Screen mapper for value data + #: Screen mapper for value data value_mapper = Instance(AbstractMapper) # Convenience properties that correspond to either index_mapper or # value_mapper, depending on the orientation of the plot. - # Corresponds to either **index_mapper** or **value_mapper**, depending on - # the orientation of the plot. + #: Corresponds to either **index_mapper** or **value_mapper**, depending on + #: the orientation of the plot. x_mapper = Property - # Corresponds to either **value_mapper** or **index_mapper**, depending on - # the orientation of the plot. + #: Corresponds to either **value_mapper** or **index_mapper**, depending on + #: the orientation of the plot. y_mapper = Property - # Convenience property for accessing the index data range. + #: Convenience property for accessing the index data range. index_range = Property - # Convenience property for accessing the value data range. + #: Convenience property for accessing the value data range. value_range = Property - # The type of hit-testing that is appropriate for this renderer. - # - # * 'line': Computes Euclidean distance to the line between the - # nearest adjacent points. - # * 'point': Checks for adjacency to a marker or point. + #: The type of hit-testing that is appropriate for this renderer. + #: + #: * 'line': Computes Euclidean distance to the line between the + #: nearest adjacent points. + #: * 'point': Checks for adjacency to a marker or point. hittest_type = Enum("point", "line") #------------------------------------------------------------------------ # Appearance-related traits #------------------------------------------------------------------------ - # The orientation of the index axis. + #: The orientation of the index axis. orientation = Enum("h", "v") - # Overall alpha value of the image. Ranges from 0.0 for transparent to 1.0 + #: Overall alpha value of the image. Ranges from 0.0 for transparent to 1.0 alpha = Range(0.0, 1.0, 1.0) #------------------------------------------------------------------------ # Convenience readonly properties for common annotations #------------------------------------------------------------------------ - # Read-only property for horizontal grid. + #: Read-only property for horizontal grid. hgrid = Property - # Read-only property for vertical grid. + #: Read-only property for vertical grid. vgrid = Property - # Read-only property for x-axis. + #: Read-only property for x-axis. x_axis = Property - # Read-only property for y-axis. + #: Read-only property for y-axis. y_axis = Property - # Read-only property for labels. + #: Read-only property for labels. labels = Property @@ -100,26 +100,26 @@ class BaseXYPlot(AbstractPlotRenderer): # Other public traits #------------------------------------------------------------------------ - # Does the plot use downsampling? - # This is not used right now. It needs an implementation of robust, fast - # downsampling, which does not exist yet. + #: Does the plot use downsampling? + #: This is not used right now. It needs an implementation of robust, fast + #: downsampling, which does not exist yet. use_downsampling = Bool(False) - # Does the plot use a spatial subdivision structure for fast hit-testing? - # This makes data updates slower, but makes hit-tests extremely fast. + #: Does the plot use a spatial subdivision structure for fast hit-testing? + #: This makes data updates slower, but makes hit-tests extremely fast. use_subdivision = Bool(False) - # Overrides the default background color trait in PlotComponent. + #: Overrides the default background color trait in PlotComponent. bgcolor = "transparent" # This just turns on a simple drawing of the X and Y axes... not a long # term solution, but good for testing. - # Defines the origin axis color, for testing. + #: Defines the origin axis color, for testing. origin_axis_color = black_color_trait - # Defines a the origin axis width, for testing. + #: Defines a the origin axis width, for testing. origin_axis_width = Float(1.0) - # Defines the origin axis visibility, for testing. + #: Defines the origin axis visibility, for testing. origin_axis_visible = Bool(False) #------------------------------------------------------------------------ diff --git a/chaco/candle_plot.py b/chaco/candle_plot.py index ce2f1cf3b..1cbb8726f 100644 --- a/chaco/candle_plot.py +++ b/chaco/candle_plot.py @@ -41,25 +41,25 @@ class CandlePlot(BaseCandlePlot): # Data-related traits #------------------------------------------------------------------------ - # The minimum values at each index point. If None, then no stem and no - # endcap line will be drawn below each bar. + #: The minimum values at each index point. If None, then no stem and no + #: endcap line will be drawn below each bar. min_values = Instance(AbstractDataSource) - # The "lower" extent of the "bar", i.e. the value closest to the - # corresponding value in min_values at each index. + #: The "lower" extent of the "bar", i.e. the value closest to the + #: corresponding value in min_values at each index. bar_min = Instance(AbstractDataSource) - # Values that appear inside the bar, between bar_min and bar_max. These - # Are usually mean or median values, and are rendered with a solid line - # of a different color than the bar fill color. This can be None. + #: Values that appear inside the bar, between bar_min and bar_max. These + #: Are usually mean or median values, and are rendered with a solid line + #: of a different color than the bar fill color. This can be None. center_values = Instance(AbstractDataSource) - # The "upper" extent of the "bar", i.e. the value closest to the - # corresponding value in max_values at each index. + #: The "upper" extent of the "bar", i.e. the value closest to the + #: corresponding value in max_values at each index. bar_max = Instance(AbstractDataSource) - # The maximum value at each index point. If None, then no stem and no - # endcap line will be drawn above each bar. + #: The maximum value at each index point. If None, then no stem and no + #: endcap line will be drawn above each bar. max_values = Instance(AbstractDataSource) value = Property diff --git a/chaco/cmap_image_plot.py b/chaco/cmap_image_plot.py index 8a8ec9386..55df2ce9d 100644 --- a/chaco/cmap_image_plot.py +++ b/chaco/cmap_image_plot.py @@ -28,24 +28,24 @@ class CMapImagePlot(ImagePlot): # Data-related traits #------------------------------------------------------------------------ - # Maps from scalar data values in self.data.value to color tuples + #: Maps from scalar data values in self.data.value to color tuples value_mapper = Instance(AbstractColormap) - # Convenience property for value_mapper as color_mapper + #: Convenience property for value_mapper as color_mapper color_mapper = Property - # Convenience property for accessing the data range of the mapper. + #: Convenience property for accessing the data range of the mapper. value_range = Property - # alpha value to use to fade out unselected data points when there is an - # active selection + #: alpha value to use to fade out unselected data points when there is an + #: active selection fade_alpha = Float(0.3) #fade_background = Tuple((255,255,255)) - # RGB color to use to fade out unselected points. + #: RGB color to use to fade out unselected points. fade_background = Tuple((0,0,0)) - # whether to pre-compute the full colormapped RGB(A) image + #: whether to pre-compute the full colormapped RGB(A) image cache_full_map = Bool(True) #------------------------------------------------------------------------ diff --git a/chaco/color_bar.py b/chaco/color_bar.py index a1f0a4742..01452aa49 100644 --- a/chaco/color_bar.py +++ b/chaco/color_bar.py @@ -23,53 +23,53 @@ class ColorBar(AbstractPlotRenderer): """ A color bar for a color-mapped plot. """ - # Screen mapper for index data. + #: Screen mapper for index data. index_mapper = Instance(AbstractMapper) - # Screen mapper for color data + #: Screen mapper for color data color_mapper = Property #Instance(ColorMapper) - # Screen mapper for value data (synonym for color_mapper) + #: Screen mapper for value data (synonym for color_mapper) value_mapper = Property(depends_on='color_mapper') - # Optional index data source for generic tools to attach metadata to. + #: Optional index data source for generic tools to attach metadata to. index = Property - # Optional color-mapped plot that this color bar references. If specified, - # the plot must have a **color_mapper** attribute. + #: Optional color-mapped plot that this color bar references. If specified, + #: the plot must have a **color_mapper** attribute. plot = Any - # Is there a visible grid on the colorbar? + #: Is there a visible grid on the colorbar? grid_visible = Bool(True) - # Is there a visible axis on the colorbar? + #: Is there a visible axis on the colorbar? axis_visible = Bool(True) - # Corresponds to either **index_mapper** or None, depending on - # the orientation of the plot. + #: Corresponds to either **index_mapper** or None, depending on + #: the orientation of the plot. x_mapper = Property - # Corresponds to either **index_mapper** or None, depending on - # the orientation of the plot. + #: Corresponds to either **index_mapper** or None, depending on + #: the orientation of the plot. y_mapper = Property #------------------------------------------------------------------------ # Override default values of inherited traits #------------------------------------------------------------------------ - # The border is visible (overrides enable.Component). + #: The border is visible (overrides enable.Component). border_visible = True - # The orientation of the index axis. + #: The orientation of the index axis. orientation = Enum('v', 'h') - # Should the bar go left-to-right or bottom-to-top (normal) or the reverse? + #: Should the bar go left-to-right or bottom-to-top (normal) or the reverse? direction = Enum('normal', 'flipped') - # Overrides the default background color trait in PlotComponent. + #: Overrides the default background color trait in PlotComponent. bgcolor = 'transparent' - # Draw layers in "draw order" + #: Draw layers in "draw order" use_draw_order = True - # Default width is 40 pixels (overrides enable.CoordinateBox) + #: Default width is 40 pixels (overrides enable.CoordinateBox) width = 40 - # Faux origin for the axis to look at + #: Faux origin for the axis to look at origin = Enum('bottom left', 'top left', 'bottom right', 'top right') #------------------------------------------------------------------------ diff --git a/chaco/color_mapper.py b/chaco/color_mapper.py index 0220e3af4..84f539bf5 100644 --- a/chaco/color_mapper.py +++ b/chaco/color_mapper.py @@ -24,13 +24,13 @@ class ColorMapTemplate(HasTraits): A class representing the state of a ColorMapper, for use when persisting plots. """ - # The segment data of the color map. + #: The segment data of the color map. segment_map = Any - # The number of steps in the color map. + #: The number of steps in the color map. steps = Int(256) - # Low end of the color map range. + #: Low end of the color map range. range_low_setting = Trait('auto', 'auto', Float) - # High end of the color map range. + #: High end of the color map range. range_high_setting = Trait('auto', 'auto', Float) def __init__(self, colormap=None, **kwtraits): @@ -77,22 +77,22 @@ class ColorMapper(AbstractColormap): ColorMapper constructor. """ - # The color table. + #: The color table. color_bands = Property(Array) - # The total number of color steps in the map. + #: The total number of color steps in the map. steps = Int(256) - # The name of this color map. + #: The name of this color map. name = Str - # Not used. + #: Not used. low_pos = None - # Not used. + #: Not used. high_pos = None - # A generic "update" event that generally means that anything that relies - # on this mapper for visual output should do a redraw or repaint. + #: A generic "update" event that generally means that anything that relies + #: on this mapper for visual output should do a redraw or repaint. updated = Event # Are the mapping arrays out of date? diff --git a/chaco/colormapped_scatterplot.py b/chaco/colormapped_scatterplot.py index 11871daa6..d10e0a0c0 100644 --- a/chaco/colormapped_scatterplot.py +++ b/chaco/colormapped_scatterplot.py @@ -41,34 +41,34 @@ class ColormappedScatterPlot(ScatterPlot): behaves like a normal ScatterPlot. """ - # Source for color data. + #: Source for color data. color_data = Instance(ArrayDataSource) - # Mapping for colors. + #: Mapping for colors. color_mapper = Instance(AbstractColormap) - # The alpha value to apply to the result of the color-mapping process. - # (This makes it easier to create color maps without having to worry - # about alpha.) + #: The alpha value to apply to the result of the color-mapping process. + #: (This makes it easier to create color maps without having to worry + #: about alpha.) fill_alpha = Float(1.0) - # Determines what drawing approach to use: - # - # banded: - # Draw the points color-band by color-band, thus reducing the number of - # set_stroke_color() calls. Disadvantage is that some colors will - # appear more prominently than others if there are a lot of - # overlapping points. - # bruteforce: - # Set the stroke color before drawing each marker. Slower, but doesn't - # produce the banding effect that puts some colors on top of others; - # useful if there is a lot of overlap of the data. - # auto: - # Determines which render method to use based on the number of points - # - # TODO: Based on preliminary results, "banded" isn't significantly - # more expensive than "bruteforce" for small datasets (<1000), - # so perhaps banded should be removed. + #: Determines what drawing approach to use: + #: + #: banded: + #: Draw the points color-band by color-band, thus reducing the number of + #: set_stroke_color() calls. Disadvantage is that some colors will + #: appear more prominently than others if there are a lot of + #: overlapping points. + #: bruteforce: + #: Set the stroke color before drawing each marker. Slower, but doesn't + #: produce the banding effect that puts some colors on top of others; + #: useful if there is a lot of overlap of the data. + #: auto: + #: Determines which render method to use based on the number of points + #: + #: TODO: Based on preliminary results, "banded" isn't significantly + #: more expensive than "bruteforce" for small datasets (<1000), + #: so perhaps banded should be removed. render_method = Enum("auto", "banded", "bruteforce") # A dict mapping color-map indices to arrays of indices into self.data. @@ -76,7 +76,7 @@ class ColormappedScatterPlot(ScatterPlot): # This mapping is only valid if **_cache_valid** is True. _index_bands = Dict() - # Traits UI View for customizing the plot. Overrides the ScatterPlot value. + #: Traits UI View for customizing the plot. Overrides the ScatterPlot value. traits_view = ColormappedScatterPlotView() #------------------------------------------------------------------------ diff --git a/chaco/colormapped_selection_overlay.py b/chaco/colormapped_selection_overlay.py index 0424439e0..2a0193048 100644 --- a/chaco/colormapped_selection_overlay.py +++ b/chaco/colormapped_selection_overlay.py @@ -17,23 +17,23 @@ class ColormappedSelectionOverlay(AbstractOverlay): points to a very low alpha. """ - # The ColormappedScatterPlot that this overlay is listening to. - # By default, it looks at self.component + #: The ColormappedScatterPlot that this overlay is listening to. + #: By default, it looks at self.component plot = Property - # The amount to fade the unselected points. + #: The amount to fade the unselected points. fade_alpha = Float(0.15) - # The minimum difference, in float percent, between the starting and ending - # selection values, if range selection mode is enabled + #: The minimum difference, in float percent, between the starting and ending + #: selection values, if range selection mode is enabled minimum_delta = Float(0.01) - # Outline width for selected points. + #: Outline width for selected points. selected_outline_width = Float(1.0) - # Outline width for unselected points. + #: Outline width for unselected points. unselected_outline_width = Float(0.0) - # The type of selection used by the data source. + #: The type of selection used by the data source. selection_type = Enum('range', 'mask') _plot = Instance(ColormappedScatterPlot) diff --git a/chaco/contour_line_plot.py b/chaco/contour_line_plot.py index 5f53dd6dd..1cb5dad8c 100644 --- a/chaco/contour_line_plot.py +++ b/chaco/contour_line_plot.py @@ -27,20 +27,20 @@ class ContourLinePlot(BaseContourPlot): # Data-related traits #------------------------------------------------------------------------ - # The thickness(es) of the contour lines. - # It can be either a scalar value, valid for all contour lines, or a list - # of widths. If the list is too short with respect to then number of - # contour lines, the values are repeated from the beginning of the list. - # Widths are associated with levels of increasing value. + #: The thickness(es) of the contour lines. + #: It can be either a scalar value, valid for all contour lines, or a list + #: of widths. If the list is too short with respect to then number of + #: contour lines, the values are repeated from the beginning of the list. + #: Widths are associated with levels of increasing value. widths = Trait(1.0, Float, List) - # The line dash style(s). + #: The line dash style(s). styles = Trait("signed", Str, List) - # Line style for positive levels. + #: Line style for positive levels. positive_style = LineStyle("solid") - # Line style for negative levels. + #: Line style for negative levels. negative_style = LineStyle("dash") #------------------------------------------------------------------------ diff --git a/chaco/cross_plot_frame.py b/chaco/cross_plot_frame.py index b66ea8f37..d459159cc 100644 --- a/chaco/cross_plot_frame.py +++ b/chaco/cross_plot_frame.py @@ -32,22 +32,22 @@ class CrossPlotFrame(BasePlotFrame): This class will be removed sometime in the future. """ - # Slots or positions on the frame where plot components can place themselves. - # Overrides PlotFrame. + #: Slots or positions on the frame where plot components can place themselves. + #: Overrides PlotFrame. slot_names = ("center", "left", "right", "top", "bottom") - # Default width and height. Class attribute. + #: Default width and height. Class attribute. default_bounds = (500,500) # The sizes of the various areas - # Width of the left slot. + #: Width of the left slot. left_width = Float(50.0) - # Width of the right slot. + #: Width of the right slot. right_width = Float(50.0) - # Height of the top slot. + #: Height of the top slot. top_height = Float(50.0) - # Height of the bottom slot. + #: Height of the bottom slot. bottom_height = Float(50.0) # Does the component need to do a layout call? diff --git a/chaco/data_label.py b/chaco/data_label.py index 599ef53b6..53e23ca3a 100644 --- a/chaco/data_label.py +++ b/chaco/data_label.py @@ -158,106 +158,106 @@ class DataLabel(ToolTip): Optionally, an arrow is drawn to the point. """ - # The symbol to use if **marker** is set to "custom". This attribute must - # be a compiled path for the given Kiva context. + #: The symbol to use if **marker** is set to "custom". This attribute must + #: be a compiled path for the given Kiva context. custom_symbol = Any - # The point in data space where this label should anchor itself. + #: The point in data space where this label should anchor itself. data_point = ArrayOrNone() - # The location of the data label relative to the data point. + #: The location of the data label relative to the data point. label_position = LabelPositionTrait - # The format string that determines the label's text. This string is - # formatted using a dict containing the keys 'x' and 'y', corresponding to - # data space values. + #: The format string that determines the label's text. This string is + #: formatted using a dict containing the keys 'x' and 'y', corresponding to + #: data space values. label_format = Str("(%(x)f, %(y)f)") - # The text to show on the label, or above the coordinates for the label, if - # show_label_coords is True + #: The text to show on the label, or above the coordinates for the label, if + #: show_label_coords is True label_text = Str - # Flag whether to show coordinates with the label or not. + #: Flag whether to show coordinates with the label or not. show_label_coords = Bool(True) - # Does the label clip itself against the main plot area? If not, then - # the label draws into the padding area (where axes typically reside). + #: Does the label clip itself against the main plot area? If not, then + #: the label draws into the padding area (where axes typically reside). clip_to_plot = Bool(True) - # The center x position (average of x and x2) + #: The center x position (average of x and x2) xmid = Property(Float, depends_on=['x', 'x2']) - # The center y position (average of y and y2) + #: The center y position (average of y and y2) ymid = Property(Float, depends_on=['y', 'y2']) - # 'box' is a simple rectangular box, with an arrow that is a single line - # with an arrowhead at the data point. - # 'bubble' can be given rounded corners (by setting `corner_radius`), and - # the 'arrow' is a thin triangular wedge with its point at the data point. - # When label_style is 'bubble', the following traits are ignored: - # arrow_size, arrow_color, arrow_root, and arrow_max_length. + #: 'box' is a simple rectangular box, with an arrow that is a single line + #: with an arrowhead at the data point. + #: 'bubble' can be given rounded corners (by setting `corner_radius`), and + #: the 'arrow' is a thin triangular wedge with its point at the data point. + #: When label_style is 'bubble', the following traits are ignored: + #: arrow_size, arrow_color, arrow_root, and arrow_max_length. label_style = Enum('box', 'bubble') #---------------------------------------------------------------------- # Marker traits #---------------------------------------------------------------------- - # Mark the point on the data that this label refers to? + #: Mark the point on the data that this label refers to? marker_visible = Bool(True) - # The type of marker to use. This is a mapped trait using strings as the - # keys. + #: The type of marker to use. This is a mapped trait using strings as the + #: keys. marker = MarkerTrait - # The pixel size of the marker (doesn't include the thickness of the - # outline). + #: The pixel size of the marker (doesn't include the thickness of the + #: outline). marker_size = Int(4) - # The thickness, in pixels, of the outline to draw around the marker. - # If this is 0, no outline will be drawn. + #: The thickness, in pixels, of the outline to draw around the marker. + #: If this is 0, no outline will be drawn. marker_line_width = Float(1.0) - # The color of the inside of the marker. + #: The color of the inside of the marker. marker_color = ColorTrait("red") - # The color out of the border drawn around the marker. + #: The color out of the border drawn around the marker. marker_line_color = ColorTrait("black") #---------------------------------------------------------------------- # Arrow traits #---------------------------------------------------------------------- - # Draw an arrow from the label to the data point? Only - # used if **data_point** is not None. + #: Draw an arrow from the label to the data point? Only + #: used if **data_point** is not None. arrow_visible = Bool(True) # FIXME: replace with some sort of ArrowStyle - # The length of the arrowhead, in screen points (e.g., pixels). + #: The length of the arrowhead, in screen points (e.g., pixels). arrow_size = Float(10) - # The color of the arrow. + #: The color of the arrow. arrow_color = ColorTrait("black") - # The position of the base of the arrow on the label. If this - # is 'auto', then the label uses **label_position**. Otherwise, it - # treats the label as if it were at the label position indicated by - # this attribute. + #: The position of the base of the arrow on the label. If this + #: is 'auto', then the label uses **label_position**. Otherwise, it + #: treats the label as if it were at the label position indicated by + #: this attribute. arrow_root = Trait("auto", "auto", "top left", "top right", "bottom left", "bottom right", "top center", "bottom center", "left center", "right center") - # The minimum length of the arrow before it will be drawn. By default, - # the arrow will be drawn regardless of how short it is. + #: The minimum length of the arrow before it will be drawn. By default, + #: the arrow will be drawn regardless of how short it is. arrow_min_length = Float(0) - # The maximum length of the arrow before it will be drawn. By default, - # the arrow will be drawn regardless of how long it is. + #: The maximum length of the arrow before it will be drawn. By default, + #: the arrow will be drawn regardless of how long it is. arrow_max_length = Float(inf) #---------------------------------------------------------------------- # Bubble traits #---------------------------------------------------------------------- - # The radius (in screen coordinates) of the curved corners of the "bubble". + #: The radius (in screen coordinates) of the curved corners of the "bubble". corner_radius = Float(10) #------------------------------------------------------------------------- diff --git a/chaco/data_range_1d.py b/chaco/data_range_1d.py index 42c9e122e..587993898 100644 --- a/chaco/data_range_1d.py +++ b/chaco/data_range_1d.py @@ -25,63 +25,63 @@ class DataRange1D(BaseDataRange): """ Represents a 1-D data range. """ - # The actual value of the lower bound of this range (overrides - # AbstractDataRange). To set it, use **low_setting**. + #: The actual value of the lower bound of this range (overrides + #: AbstractDataRange). To set it, use **low_setting**. low = Property - # The actual value of the upper bound of this range (overrides - # AbstractDataRange). To set it, use **high_setting**. + #: The actual value of the upper bound of this range (overrides + #: AbstractDataRange). To set it, use **high_setting**. high = Property - # Property for the lower bound of this range (overrides AbstractDataRange). - # - # * 'auto': The lower bound is automatically set at or below the minimum - # of the data. - # * 'track': The lower bound tracks the upper bound by **tracking_amount**. - # * CFloat: An explicit value for the lower bound + #: Property for the lower bound of this range (overrides AbstractDataRange). + #: + #: * 'auto': The lower bound is automatically set at or below the minimum + #: of the data. + #: * 'track': The lower bound tracks the upper bound by **tracking_amount**. + #: * CFloat: An explicit value for the lower bound low_setting = Property(Trait('auto', 'auto', 'track', CFloat)) - # Property for the upper bound of this range (overrides AbstractDataRange). - # - # * 'auto': The upper bound is automatically set at or above the maximum - # of the data. - # * 'track': The upper bound tracks the lower bound by **tracking_amount**. - # * CFloat: An explicit value for the upper bound + #: Property for the upper bound of this range (overrides AbstractDataRange). + #: + #: * 'auto': The upper bound is automatically set at or above the maximum + #: of the data. + #: * 'track': The upper bound tracks the lower bound by **tracking_amount**. + #: * CFloat: An explicit value for the upper bound high_setting = Property(Trait('auto', 'auto', 'track', CFloat)) - # Do "auto" bounds imply an exact fit to the data? If False, - # they pad a little bit of margin on either side. + #: Do "auto" bounds imply an exact fit to the data? If False, + #: they pad a little bit of margin on either side. tight_bounds = Bool(True) - # A user supplied function returning the proper bounding interval. - # bounds_func takes (data_low, data_high, margin, tight_bounds) - # and returns (low, high) + #: A user supplied function returning the proper bounding interval. + #: bounds_func takes (data_low, data_high, margin, tight_bounds) + #: and returns (low, high) bounds_func = Callable - # The amount of margin to place on either side of the data, expressed as - # a percentage of the full data width + #: The amount of margin to place on either side of the data, expressed as + #: a percentage of the full data width margin = Float(0.05) - # The minimum percentage difference between low and high. That is, - # (high-low) >= epsilon * low. - # Used to be 1.0e-20 but chaco cannot plot at such a precision! + #: The minimum percentage difference between low and high. That is, + #: (high-low) >= epsilon * low. + #: Used to be 1.0e-20 but chaco cannot plot at such a precision! epsilon = CFloat(1.0e-10) - # When either **high** or **low** tracks the other, track by this amount. + #: When either **high** or **low** tracks the other, track by this amount. default_tracking_amount = CFloat(20.0) - # The current tracking amount. This value changes with zooming. + #: The current tracking amount. This value changes with zooming. tracking_amount = default_tracking_amount - # Default tracking state. This value is used when self.reset() is called. - # - # * 'auto': Both bounds reset to 'auto'. - # * 'high_track': The high bound resets to 'track', and the low bound - # resets to 'auto'. - # * 'low_track': The low bound resets to 'track', and the high bound - # resets to 'auto'. + #: Default tracking state. This value is used when self.reset() is called. + #: + #: * 'auto': Both bounds reset to 'auto'. + #: * 'high_track': The high bound resets to 'track', and the low bound + #: resets to 'auto'. + #: * 'low_track': The low bound resets to 'track', and the high bound + #: resets to 'auto'. default_state = Enum('auto', 'high_track', 'low_track') - # FIXME: this attribute is not used anywhere, is it safe to remove it? - # Is this range dependent upon another range? + #: FIXME: this attribute is not used anywhere, is it safe to remove it? + #: Is this range dependent upon another range? fit_to_subset = Bool(False) #------------------------------------------------------------------------ diff --git a/chaco/data_range_2d.py b/chaco/data_range_2d.py index 1f8676512..075b91c2c 100644 --- a/chaco/data_range_2d.py +++ b/chaco/data_range_2d.py @@ -21,16 +21,16 @@ class DataRange2D(BaseDataRange): class supports only rectangular regions for now. """ - # The actual value of the lower bound of this range. To set it, use - # **low_setting**. + #: The actual value of the lower bound of this range. To set it, use + #: **low_setting**. low = Property # (2,) array of lower-left x,y - # The actual value of the upper bound of this range. To set it, use - # **high_setting**. + #: The actual value of the upper bound of this range. To set it, use + #: **high_setting**. high = Property # (2,) array of upper-right x,y - # Property for the lower bound of this range (overrides AbstractDataRange). + #: Property for the lower bound of this range (overrides AbstractDataRange). low_setting = Property - # Property for the upper bound of this range (overrides AbstractDataRange). + #: Property for the upper bound of this range (overrides AbstractDataRange). high_setting = Property # The 2-D grid range is actually implemented as two 1-D ranges, which can @@ -38,17 +38,17 @@ class supports only rectangular regions for now. # instances; in that case, the DataRange2D's sources are removed from # its old 1-D dataranges and added to the new one. - # Property for the range in the x-dimension. + #: Property for the range in the x-dimension. x_range = Property - # Property for the range in the y-dimension. + #: Property for the range in the y-dimension. y_range = Property - # Do "auto" bounds imply an exact fit to the data? (One Boolean per - # dimension) If False, the bounds pad a little bit of margin on either - # side. + #: Do "auto" bounds imply an exact fit to the data? (One Boolean per + #: dimension) If False, the bounds pad a little bit of margin on either + #: side. tight_bounds = Tuple(Bool(True), Bool(True)) - # The minimum percentage difference between low and high for each - # dimension. That is, (high-low) >= epsilon * low. + #: The minimum percentage difference between low and high for each + #: dimension. That is, (high-low) >= epsilon * low. epsilon = Tuple(CFloat(1.0e-4), CFloat(1.0e-4)) #------------------------------------------------------------------------ diff --git a/chaco/data_view.py b/chaco/data_view.py index a4c114800..4120dec15 100644 --- a/chaco/data_view.py +++ b/chaco/data_view.py @@ -89,111 +89,111 @@ class DataView(OverlayPlotContainer): just like a normal PlotContainer. """ - # The orientation of the index axis. + #: The orientation of the index axis. orientation = Enum("h", "v") - # The default location of the origin for new plots + #: The default location of the origin for new plots default_origin = Enum("bottom left", "top left", "bottom right", "top right") - # The origin reported to axes, etc + #: The origin reported to axes, etc origin = Property(depends_on='default_origin') # Whether our map_screen and map_data should treat screen-space # coords as being in our coordinate space or in our contained # coordinate space. - # The mapper to use for the index data. + #: The mapper to use for the index data. index_mapper = Instance(Base1DMapper) - # The mapper to use for value data. + #: The mapper to use for value data. value_mapper = Instance(Base1DMapper) - # For x-y plots, the scale of the index axis. + #: For x-y plots, the scale of the index axis. index_scale = Enum("linear", "log") - # For x-y plots, the scale of the index axis. + #: For x-y plots, the scale of the index axis. value_scale = Enum("linear", "log") - # The range used for the index data. + #: The range used for the index data. index_range = Property - # The range used for the value data. + #: The range used for the value data. value_range = Property - # The 2-D data range whose x- and y-ranges are exposed as the - # **index_range** and **value_range** property traits. This allows - # supporting both XY plots and 2-D (image) plots. + #: The 2-D data range whose x- and y-ranges are exposed as the + #: **index_range** and **value_range** property traits. This allows + #: supporting both XY plots and 2-D (image) plots. range2d = Instance(DataRange2D) - # Convenience property that offers access to whatever mapper corresponds - # to the X-axis. + #: Convenience property that offers access to whatever mapper corresponds + #: to the X-axis. x_mapper = OrientedMapperProperty - # Convenience property that offers access to whatever mapper corresponds - # to the Y-axis + #: Convenience property that offers access to whatever mapper corresponds + #: to the Y-axis y_mapper = OrientedMapperProperty #------------------------------------------------------------------------ # Axis and Grids #------------------------------------------------------------------------ - # The horizontal axis. Its position relative to the plot - # area can be "top", "bottom", or "float". The default position for a new - # x-axis is "bottom". - # - # TODO: For now, this is an instance of AbstractOverlay instead of PlotAxis - # because scales_axis.PlotAxis doesn't inherit from PlotAxis, but instead is a - # semi-reimplementation. Thus, rather than making scales_axis.PlotAxis - # inherit a concrete class, I chose to loosen this trait by specifying - # a more general base class of PlotAxis. This incurs lower risk of subtle - # and difficult-to-catch bugs being introduced by changes to the - # axis.PlotAxis class. This same comment applies to the y_axis trait - # below. --pwang - #x_axis = Instance(PlotAxis) + #: The horizontal axis. Its position relative to the plot + #: area can be "top", "bottom", or "float". The default position for a new + #: x-axis is "bottom". + #: + #: TODO: For now, this is an instance of AbstractOverlay instead of PlotAxis + #: because scales_axis.PlotAxis doesn't inherit from PlotAxis, but instead is a + #: semi-reimplementation. Thus, rather than making scales_axis.PlotAxis + #: inherit a concrete class, I chose to loosen this trait by specifying + #: a more general base class of PlotAxis. This incurs lower risk of subtle + #: and difficult-to-catch bugs being introduced by changes to the + #: axis.PlotAxis class. This same comment applies to the y_axis trait + #: below. --pwang + #:x_axis = Instance(PlotAxis) x_axis = Instance(AbstractOverlay) - # The vertical axis. Its position relative to the plot - # area can be "left", "right", or "float". The default position for a new - # y-axis is "left". - #y_axis = Instance(PlotAxis) + #: The vertical axis. Its position relative to the plot + #: area can be "left", "right", or "float". The default position for a new + #: y-axis is "left". + #:y_axis = Instance(PlotAxis) y_axis = Instance(AbstractOverlay) - # The grid that intersects the x-axis, i.e., a set of vertical lines. + #: The grid that intersects the x-axis, i.e., a set of vertical lines. x_grid = Instance(PlotGrid) - # The grid that intersects the y-axis, i.e., a set of horizontal lines. + #: The grid that intersects the y-axis, i.e., a set of horizontal lines. y_grid = Instance(PlotGrid) - # Whether to automatically create the x_axis and y_axis if they were not - # already set by the caller. + #: Whether to automatically create the x_axis and y_axis if they were not + #: already set by the caller. auto_axis = Bool(True) - # Whether to automatically create the x_grid and y_grid if they were not - # already set by the caller. + #: Whether to automatically create the x_grid and y_grid if they were not + #: already set by the caller. auto_grid = Bool(True) - # Convenience property for accessing the index axis, which can be X or Y, - # depending on **orientation**. + #: Convenience property for accessing the index axis, which can be X or Y, + #: depending on **orientation**. index_axis = AxisProperty - # Convenience property for accessing the value axis, which can be Y or X, - # depending on **orientation**. + #: Convenience property for accessing the value axis, which can be Y or X, + #: depending on **orientation**. value_axis = AxisProperty - # Convenience property for accessing the index grid, which can be horizontal - # or vertical, depending on **orientation**. + #: Convenience property for accessing the index grid, which can be horizontal + #: or vertical, depending on **orientation**. index_grid = GridProperty - # Convenience property for accessing the value grid, which can be vertical - # or horizontal, depending on **orientation**. + #: Convenience property for accessing the value grid, which can be vertical + #: or horizontal, depending on **orientation**. value_grid = GridProperty #------------------------------------------------------------------------ # Appearance #------------------------------------------------------------------------ - # Background color (overrides Enable Component) + #: Background color (overrides Enable Component) bgcolor = "white" - # Padding defaults. + #: Padding defaults. padding_top = 50 padding_bottom = 50 padding_left = 50 diff --git a/chaco/errorbar_plot.py b/chaco/errorbar_plot.py index e50c7c59e..056c8838e 100644 --- a/chaco/errorbar_plot.py +++ b/chaco/errorbar_plot.py @@ -24,16 +24,16 @@ class ErrorBarPlot(LinePlot): """ Renders errorbars at various points. """ - # The datasource containing the low values + #: The datasource containing the low values value_low = Instance(AbstractDataSource) - # The datasource containing the high values + #: The datasource containing the high values value_high = Instance(AbstractDataSource) - # The screen-space width of the endcap bars + #: The screen-space width of the endcap bars endcap_size = Float(5.0) - # The kind of encap to render on error bars + #: The kind of encap to render on error bars endcap_style = Enum("bar", "none", None) # Override the inherited trait definition diff --git a/chaco/filled_line_plot.py b/chaco/filled_line_plot.py index 40a33b5b5..c9a197785 100644 --- a/chaco/filled_line_plot.py +++ b/chaco/filled_line_plot.py @@ -19,22 +19,22 @@ class FilledLinePlot(PolygonPlot): fill_color = Alias("face_color") - # Direction to fill. Down is towards the origin, up is towards the max + #: Direction to fill. Down is towards the origin, up is towards the max fill_direction = Enum("down", "up") - # The rendering style of the line plot. - # - # connectedpoints - # "normal" style (default); each point is connected to subsequent and - # prior points by line segments - # hold - # each point is represented by a line segment parallel to the abscissa - # (index axis) and spanning the length between the point and its - # subsequent point. - # connectedhold - # like "hold" style, but line segments are drawn at each point of the - # plot to connect the hold lines of the prior point and the current - # point. Also called a "right angle plot". + #: The rendering style of the line plot. + #: + #: connectedpoints + #: "normal" style (default); each point is connected to subsequent and + #: prior points by line segments + #: hold + #: each point is represented by a line segment parallel to the abscissa + #: (index axis) and spanning the length between the point and its + #: subsequent point. + #: connectedhold + #: like "hold" style, but line segments are drawn at each point of the + #: plot to connect the hold lines of the prior point and the current + #: point. Also called a "right angle plot". render_style = Enum("connectedpoints", "hold", "connectedhold") def _render(self, gc, points): diff --git a/chaco/grid.py b/chaco/grid.py index 40bf8018c..3b5554db3 100644 --- a/chaco/grid.py +++ b/chaco/grid.py @@ -63,73 +63,73 @@ class PlotGrid(AbstractOverlay): # Data-related traits #------------------------------------------------------------------------ - # The mapper (and associated range) that drive this PlotGrid. + #: The mapper (and associated range) that drive this PlotGrid. mapper = Instance(AbstractMapper) - # The dataspace interval between grid lines. + #: The dataspace interval between grid lines. grid_interval = Trait('auto', 'auto', Float) - # The dataspace value at which to start this grid. If None, then - # uses the mapper.range.low. + #: The dataspace value at which to start this grid. If None, then + #: uses the mapper.range.low. data_min = Trait(None, None, Float) - # The dataspace value at which to end this grid. If None, then uses - # the mapper.range.high. + #: The dataspace value at which to end this grid. If None, then uses + #: the mapper.range.high. data_max = Trait(None, None, Float) - # A callable that implements the AbstractTickGenerator Interface. + #: A callable that implements the AbstractTickGenerator Interface. tick_generator = Instance(AbstractTickGenerator) #------------------------------------------------------------------------ # Layout traits #------------------------------------------------------------------------ - # The orientation of the grid lines. "horizontal" means that the grid - # lines are parallel to the X axis and the ticker and grid interval - # refer to the Y axis. + #: The orientation of the grid lines. "horizontal" means that the grid + #: lines are parallel to the X axis and the ticker and grid interval + #: refer to the Y axis. orientation = Enum('horizontal', 'vertical') - # Draw the ticks starting at the end of the mapper range? If False, the - # ticks are drawn starting at 0. This setting can be useful to keep the - # grid from from "flashing" as the user resizes the plot area. + #: Draw the ticks starting at the end of the mapper range? If False, the + #: ticks are drawn starting at 0. This setting can be useful to keep the + #: grid from from "flashing" as the user resizes the plot area. flip_axis = Bool(False) - # Optional specification of the grid bounds in the dimension transverse - # to the ticking/gridding dimension, i.e. along the direction specified - # by self.orientation. If this is specified but transverse_mapper is - # not specified, then there is no effect. - # - # None : use self.bounds or self.component.bounds (if overlay) - # Tuple : (low, high) extents, used for every grid line - # Callable : Function that takes an array of dataspace grid ticks - # and returns either an array of shape (N,2) of (starts,ends) - # for each grid point or a single tuple (low, high) + #: Optional specification of the grid bounds in the dimension transverse + #: to the ticking/gridding dimension, i.e. along the direction specified + #: by self.orientation. If this is specified but transverse_mapper is + #: not specified, then there is no effect. + #: + #: None : use self.bounds or self.component.bounds (if overlay) + #: Tuple : (low, high) extents, used for every grid line + #: Callable : Function that takes an array of dataspace grid ticks + #: and returns either an array of shape (N,2) of (starts,ends) + #: for each grid point or a single tuple (low, high) transverse_bounds = Trait(None, Tuple, Callable) - # Mapper in the direction corresponding to self.orientation, i.e. transverse - # to the direction of self.mapper. This is used to compute the screen - # position of transverse_bounds. If this is not specified, then - # transverse_bounds has no effect, and vice versa. + #: Mapper in the direction corresponding to self.orientation, i.e. transverse + #: to the direction of self.mapper. This is used to compute the screen + #: position of transverse_bounds. If this is not specified, then + #: transverse_bounds has no effect, and vice versa. transverse_mapper = Instance(AbstractMapper) - # Dimensions that the grid is resizable in (overrides PlotComponent). + #: Dimensions that the grid is resizable in (overrides PlotComponent). resizable = "hv" #------------------------------------------------------------------------ # Appearance traits #------------------------------------------------------------------------ - # The color of the grid lines. + #: The color of the grid lines. line_color = black_color_trait - # The style (i.e., dash pattern) of the grid lines. + #: The style (i.e., dash pattern) of the grid lines. line_style = LineStyle('solid') - # The thickness, in pixels, of the grid lines. + #: The thickness, in pixels, of the grid lines. line_width = CInt(1) line_weight = Alias("line_width") - # Default Traits UI View for modifying grid attributes. + #: Default Traits UI View for modifying grid attributes. traits_view = GridView #------------------------------------------------------------------------ diff --git a/chaco/grid_data_source.py b/chaco/grid_data_source.py index 3ca4bf355..9b40122d8 100644 --- a/chaco/grid_data_source.py +++ b/chaco/grid_data_source.py @@ -22,17 +22,17 @@ class GridDataSource(AbstractDataSource): # AbstractDataSource traits #------------------------------------------------------------------------ - # The dimensionality of the indices into this data source (overrides - # AbstractDataSource). + #: The dimensionality of the indices into this data source (overrides + #: AbstractDataSource). index_dimension = Constant('image') - # The dimensionality of the value at each index point (overrides - # AbstractDataSource). + #: The dimensionality of the value at each index point (overrides + #: AbstractDataSource). value_dimension = Constant('scalar') - # The sort order of the data (overrides AbstractDataSource). There is no - # overall sort order on 2-D data, but for gridded 2-D data, each axis can - # have a sort order. + #: The sort order of the data (overrides AbstractDataSource). There is no + #: overall sort order on 2-D data, but for gridded 2-D data, each axis can + #: have a sort order. sort_order =Tuple(SortOrderTrait, SortOrderTrait) #------------------------------------------------------------------------ diff --git a/chaco/grid_mapper.py b/chaco/grid_mapper.py index be04c17fc..43f1bd7c1 100644 --- a/chaco/grid_mapper.py +++ b/chaco/grid_mapper.py @@ -31,36 +31,36 @@ class GridMapper(AbstractMapper): **y_high_pos**. """ - # The data-space bounds of the mapper. + #: The data-space bounds of the mapper. range = Instance(DataRange2D) - # The screen space position of the lower bound of the horizontal axis. + #: The screen space position of the lower bound of the horizontal axis. x_low_pos = Float(0.0) - # The screen space position of the upper bound of the horizontal axis. + #: The screen space position of the upper bound of the horizontal axis. x_high_pos = Float(1.0) - # The screen space position of the lower bound of the vertical axis. + #: The screen space position of the lower bound of the vertical axis. y_low_pos = Float(0.0) - # The screen space position of the upper bound of the vertical axis. + #: The screen space position of the upper bound of the vertical axis. y_high_pos = Float(1.0) - # Convenience property for low and high positions in one structure. - # Must be a tuple (x_low_pos, x_high_pos, y_low_pos, y_high_pos). + #: Convenience property for low and high positions in one structure. + #: Must be a tuple (x_low_pos, x_high_pos, y_low_pos, y_high_pos). screen_bounds = Property - # Should the mapper stretch the dataspace when its screen space bounds are - # modified (default), or should it preserve the screen-to-data ratio and - # resize the data bounds? If the latter, it will only try to preserve - # the ratio if both screen and data space extents are non-zero. + #: Should the mapper stretch the dataspace when its screen space bounds are + #: modified (default), or should it preserve the screen-to-data ratio and + #: resize the data bounds? If the latter, it will only try to preserve + #: the ratio if both screen and data space extents are non-zero. stretch_data_x = DelegatesTo("_xmapper", prefix="stretch_data") stretch_data_y = DelegatesTo("_ymapper", prefix="stretch_data") - # Should the mapper try to maintain a fixed aspect ratio between x and y + #: Should the mapper try to maintain a fixed aspect ratio between x and y maintain_aspect_ratio = Bool - # The aspect ratio that we wish to maintain + #: The aspect ratio that we wish to maintain aspect_ratio = Float(1.0) #------------------------------------------------------------------------ diff --git a/chaco/horizon_plot.py b/chaco/horizon_plot.py index 27da33944..a412a7ddd 100644 --- a/chaco/horizon_plot.py +++ b/chaco/horizon_plot.py @@ -32,11 +32,11 @@ class HorizonPlot(BaseXYPlot): mirror = Bool(False) - # FIXME There should be a way to automatically detect whether the data has - # negative bands + #: FIXME There should be a way to automatically detect whether the data has + #: negative bands negative_bands = Bool(True) - # Override parent traits + #: Override parent traits orientation = 'h' diff --git a/chaco/image_data.py b/chaco/image_data.py index c8351f91a..23941cb55 100644 --- a/chaco/image_data.py +++ b/chaco/image_data.py @@ -18,46 +18,46 @@ class ImageData(AbstractDataSource): dimensions. The appropriate dimensionality of the value array depends on the context in which the ImageData instance will be used. """ - # The dimensionality of the data. + #: The dimensionality of the data. dimension = ReadOnly(DimensionTrait('image')) - # Depth of the values at each i,j. Values that are used include: - # - # * 3: color images, without alpha channel - # * 4: color images, with alpha channel + #: Depth of the values at each i,j. Values that are used include: + #: + #: * 3: color images, without alpha channel + #: * 4: color images, with alpha channel value_depth = Int(1) # TODO: Modify ImageData to explicitly support scalar # value arrays, as needed by CMapImagePlot - # Holds the grid data that forms the image. The shape of the array is - # (N, M, D) where: - # - # * D is 1, 3, or 4. - # * N is the length of the y-axis. - # * M is the length of the x-axis. - # - # Thus, data[0,:,:] must be the first row of data. If D is 1, then - # the array must be of type float; if D is 3 or 4, then the array - # must be of type uint8. - # - # NOTE: If this ImageData was constructed with a transposed data array, - # then internally it is still transposed (i.e., the x-axis is the first axis - # and the y-axis is the second), and the **data** array property might not be - # contiguous. If contiguousness is required and calling copy() is too - # expensive, use the **raw_value** attribute. Also note that setting this - # trait does not change the value of **transposed**, - # so be sure to set it to its proper value when using the same ImageData - # instance interchangeably to store transposed and non-transposed data. + #: Holds the grid data that forms the image. The shape of the array is + #: (N, M, D) where: + #: + #: * D is 1, 3, or 4. + #: * N is the length of the y-axis. + #: * M is the length of the x-axis. + #: + #: Thus, data[0,:,:] must be the first row of data. If D is 1, then + #: the array must be of type float; if D is 3 or 4, then the array + #: must be of type uint8. + #: + #: NOTE: If this ImageData was constructed with a transposed data array, + #: then internally it is still transposed (i.e., the x-axis is the first axis + #: and the y-axis is the second), and the **data** array property might not be + #: contiguous. If contiguousness is required and calling copy() is too + #: expensive, use the **raw_value** attribute. Also note that setting this + #: trait does not change the value of **transposed**, + #: so be sure to set it to its proper value when using the same ImageData + #: instance interchangeably to store transposed and non-transposed data. data = Property(ImageTrait) - # Is **raw_value**, the actual underlying image data - # array, transposed from **data**? (I.e., does the first axis correspond to - # the x-direction and the second axis correspond to the y-direction?) - # - # Rather than transposing or swapping axes on the data and destroying - # continuity, this class exposes the data as both **data** and **raw_value**. + #: Is **raw_value**, the actual underlying image data + #: array, transposed from **data**? (I.e., does the first axis correspond to + #: the x-direction and the second axis correspond to the y-direction?) + #: + #: Rather than transposing or swapping axes on the data and destroying + #: continuity, this class exposes the data as both **data** and **raw_value**. transposed = Bool(False) - # A read-only attribute that exposes the underlying array. + #: A read-only attribute that exposes the underlying array. raw_value = Property(ImageTrait) diff --git a/chaco/image_plot.py b/chaco/image_plot.py index 3637a5725..fd00ac1e1 100644 --- a/chaco/image_plot.py +++ b/chaco/image_plot.py @@ -50,17 +50,17 @@ class ImagePlot(Base2DPlot): # Data-related traits #------------------------------------------------------------------------ - # Overall alpha value of the image. Ranges from 0.0 for transparent to 1.0 - # for full intensity. + #: Overall alpha value of the image. Ranges from 0.0 for transparent to 1.0 + #: for full intensity. alpha = Trait(1.0, Range(0.0, 1.0)) - # The interpolation method to use when rendering an image onto the GC. + #: The interpolation method to use when rendering an image onto the GC. interpolation = Enum("nearest", "bilinear", "bicubic") - # Bool indicating whether x-axis is flipped. + #: Bool indicating whether x-axis is flipped. x_axis_is_flipped = Property(depends_on=['orientation', 'origin']) - # Bool indicating whether y-axis is flipped. + #: Bool indicating whether y-axis is flipped. y_axis_is_flipped = Property(depends_on=['orientation', 'origin']) #------------------------------------------------------------------------ diff --git a/chaco/label.py b/chaco/label.py index 45a86379f..fda3e390e 100644 --- a/chaco/label.py +++ b/chaco/label.py @@ -32,41 +32,41 @@ class Label(HasTraits): #anchor = Enum("left", "right", "top", "bottom", "center", # "top left", "top right", "bottom left", "bottom right") - # The label text. Carriage returns (\n) are always connverted into - # line breaks. + #: The label text. Carriage returns (\n) are always connverted into + #: line breaks. text = Str - # The angle of rotation of the label. + #: The angle of rotation of the label. rotate_angle = Float(0) - # The color of the label text. + #: The color of the label text. color = black_color_trait - # The background color of the label. + #: The background color of the label. bgcolor = transparent_color_trait - # The width of the label border. If it is 0, then it is not shown. + #: The width of the label border. If it is 0, then it is not shown. border_width = Int(0) - # The color of the border. + #: The color of the border. border_color = black_color_trait - # Whether or not the border is visible + #: Whether or not the border is visible border_visible = Bool(True) - # The font of the label text. + #: The font of the label text. font = KivaFont("modern 10") - # Number of pixels of margin around the label, for both X and Y dimensions. + #: Number of pixels of margin around the label, for both X and Y dimensions. margin = Int(2) - # Number of pixels of spacing between lines of text. + #: Number of pixels of spacing between lines of text. line_spacing = Int(5) - # Number of pixels to limit the width of the label to. Lines which are - # too long will be broken to fit on word boundaries. Line width is - # calculated without considering the value of `margin`. - # A `max_width` of 0.0 means that lines will not be broken. + #: Number of pixels to limit the width of the label to. Lines which are + #: too long will be broken to fit on word boundaries. Line width is + #: calculated without considering the value of `margin`. + #: A `max_width` of 0.0 means that lines will not be broken. max_width = Float(0.0) #------------------------------------------------------------------------ diff --git a/chaco/label_axis.py b/chaco/label_axis.py index edf7eee31..8a2b3cce9 100644 --- a/chaco/label_axis.py +++ b/chaco/label_axis.py @@ -16,13 +16,13 @@ class LabelAxis(PlotAxis): """ An axis whose ticks are labeled with text instead of numbers. """ - # List of labels to use on tick marks. + #: List of labels to use on tick marks. labels = List(Str) - # The angle of rotation of the label. Only multiples of 90 are supported. + #: The angle of rotation of the label. Only multiples of 90 are supported. label_rotation = Float(0) - # List of indices of ticks + #: List of indices of ticks positions = ArrayOrNone() def _compute_tick_positions(self, gc, component=None): diff --git a/chaco/lasso_overlay.py b/chaco/lasso_overlay.py index 974ed5c47..f0cc06591 100644 --- a/chaco/lasso_overlay.py +++ b/chaco/lasso_overlay.py @@ -18,20 +18,20 @@ class LassoOverlay(AbstractOverlay): LassoOverlay gets its data from a LassoSelection. """ - # The LassoSelection that provides the data for this overlay. + #: The LassoSelection that provides the data for this overlay. lasso_selection = Instance('chaco.tools.lasso_selection.LassoSelection') - # The fill color for the selection region. + #: The fill color for the selection region. selection_fill_color = ColorTrait('lightskyblue') - # The border color for the selection region. + #: The border color for the selection region. selection_border_color = ColorTrait('dodgerblue') - # The transparency level for the selection fill color. + #: The transparency level for the selection fill color. selection_alpha = Float(0.8) - # The width of the selection border. + #: The width of the selection border. selection_border_width = Float(2.0) - # The line style of the selection border. + #: The line style of the selection border. selection_border_dash = LineStyle - # The background color (overrides AbstractOverlay). + #: The background color (overrides AbstractOverlay). bgcolor = 'clear' # Whether to draw the lasso diff --git a/chaco/legend.py b/chaco/legend.py index 21d41aff2..ce86622a4 100644 --- a/chaco/legend.py +++ b/chaco/legend.py @@ -71,89 +71,89 @@ def _render_line_scatter(self, plots, gc, x, y, width, height): class Legend(AbstractOverlay): """ A legend for a plot. """ - # The font to use for the legend text. + #: The font to use for the legend text. font = KivaFont("modern 12") - # The amount of space between the content of the legend and the border. + #: The amount of space between the content of the legend and the border. border_padding = Int(10) - # The border is visible (overrides Enable Component). + #: The border is visible (overrides Enable Component). border_visible = True - # The color of the text labels + #: The color of the text labels color = black_color_trait - # The background color of the legend (overrides AbstractOverlay). + #: The background color of the legend (overrides AbstractOverlay). bgcolor = white_color_trait - # The position of the legend with respect to its overlaid component. (This - # attribute applies only if the legend is used as an overlay.) - # - # * ur = Upper Right - # * ul = Upper Left - # * ll = Lower Left - # * lr = Lower Right + #: The position of the legend with respect to its overlaid component. (This + #: attribute applies only if the legend is used as an overlay.) + #: + #: * ur = Upper Right + #: * ul = Upper Left + #: * ll = Lower Left + #: * lr = Lower Right align = Enum("ur", "ul", "ll", "lr") - # The amount of space between legend items. + #: The amount of space between legend items. line_spacing = Int(3) - # The size of the icon or marker area drawn next to the label. + #: The size of the icon or marker area drawn next to the label. icon_bounds = List([24, 24]) - # Amount of spacing between each label and its icon. + #: Amount of spacing between each label and its icon. icon_spacing = Int(5) - # Map of labels (strings) to plot instances or lists of plot instances. The - # Legend determines the appropriate rendering of each plot's marker/line. + #: Map of labels (strings) to plot instances or lists of plot instances. The + #: Legend determines the appropriate rendering of each plot's marker/line. plots = Dict - # The list of labels to show and the order to show them in. If this - # list is blank, then the keys of self.plots is used and displayed in - # alphabetical order. Otherwise, only the items in the **labels** - # list are drawn in the legend. Labels are ordered from top to bottom. + #: The list of labels to show and the order to show them in. If this + #: list is blank, then the keys of self.plots is used and displayed in + #: alphabetical order. Otherwise, only the items in the **labels** + #: list are drawn in the legend. Labels are ordered from top to bottom. labels = List - # Whether or not to hide plots that are not visible. (This is checked during - # layout.) This option *will* filter out the items in **labels** above, so - # if you absolutely, positively want to set the items that will always - # display in the legend, regardless of anything else, then you should turn - # this option off. Otherwise, it usually makes sense that a plot renderer - # that is not visible will also not be in the legend. + #: Whether or not to hide plots that are not visible. (This is checked during + #: layout.) This option *will* filter out the items in **labels** above, so + #: if you absolutely, positively want to set the items that will always + #: display in the legend, regardless of anything else, then you should turn + #: this option off. Otherwise, it usually makes sense that a plot renderer + #: that is not visible will also not be in the legend. hide_invisible_plots = Bool(True) - # If hide_invisible_plots is False, we can still choose to render the names - # of invisible plots with an alpha. + #: If hide_invisible_plots is False, we can still choose to render the names + #: of invisible plots with an alpha. invisible_plot_alpha = Float(0.33) - # The renderer that draws the icons for the legend. + #: The renderer that draws the icons for the legend. composite_icon_renderer = Instance(AbstractCompositeIconRenderer) - # Action that the legend takes when it encounters a plot whose icon it - # cannot render: - # - # * 'skip': skip it altogether and don't render its name - # * 'blank': render the name but leave the icon blank (color=self.bgcolor) - # * 'questionmark': render a "question mark" icon + #: Action that the legend takes when it encounters a plot whose icon it + #: cannot render: + #: + #: * 'skip': skip it altogether and don't render its name + #: * 'blank': render the name but leave the icon blank (color=self.bgcolor) + #: * 'questionmark': render a "question mark" icon error_icon = Enum("skip", "blank", "questionmark") - # Should the legend clip to the bounds it needs, or to its parent? + #: Should the legend clip to the bounds it needs, or to its parent? clip_to_component = Bool(False) - # The legend is not resizable (overrides PlotComponent). + #: The legend is not resizable (overrides PlotComponent). resizable = "hv" - # An optional title string to show on the legend. + #: An optional title string to show on the legend. title = Str('') - # If True, title is at top, if False then at bottom. + #: If True, title is at top, if False then at bottom. title_at_top = Bool(True) - # The legend draws itself as in one pass when its parent is drawing - # the **draw_layer** (overrides PlotComponent). + #: The legend draws itself as in one pass when its parent is drawing + #: the **draw_layer** (overrides PlotComponent). unified_draw = True - # The legend is drawn on the overlay layer of its parent (overrides - # PlotComponent). + #: The legend is drawn on the overlay layer of its parent (overrides + #: PlotComponent). draw_layer = "overlay" #------------------------------------------------------------------------ diff --git a/chaco/lineplot.py b/chaco/lineplot.py index 382633006..62ac17627 100644 --- a/chaco/lineplot.py +++ b/chaco/lineplot.py @@ -29,45 +29,45 @@ class LinePlot(BaseXYPlot): you want can require some verbose code. The create_line_plot() function in plot_factory.py can hide some of this verbosity for common cases. """ - # The color of the line. + #: The color of the line. color = black_color_trait - # The RGBA tuple for rendering lines. It is always a tuple of length 4. - # It has the same RGB values as color_, and its alpha value is the alpha - # value of self.color multiplied by self.alpha. + #: The RGBA tuple for rendering lines. It is always a tuple of length 4. + #: It has the same RGB values as color_, and its alpha value is the alpha + #: value of self.color multiplied by self.alpha. effective_color = Property(Tuple, depends_on=['color', 'alpha']) - # The color to use to highlight the line when selected. + #: The color to use to highlight the line when selected. selected_color = ColorTrait("lightyellow") - # The style of the selected line. + #: The style of the selected line. selected_line_style = LineStyle("solid") - # The name of the key in self.metadata that holds the selection mask + #: The name of the key in self.metadata that holds the selection mask metadata_name = Str("selections") - # The thickness of the line. + #: The thickness of the line. line_width = Float(1.0) - # The line dash style. + #: The line dash style. line_style = LineStyle - # The rendering style of the line plot. - # - # connectedpoints - # "normal" style (default); each point is connected to subsequent and - # prior points by line segments - # hold - # each point is represented by a line segment parallel to the abscissa - # (index axis) and spanning the length between the point and its - # subsequent point. - # connectedhold - # like "hold" style, but line segments are drawn at each point of the - # plot to connect the hold lines of the prior point and the current - # point. Also called a "right angle plot". + #: The rendering style of the line plot. + #: + #: connectedpoints + #: "normal" style (default); each point is connected to subsequent and + #: prior points by line segments + #: hold + #: each point is represented by a line segment parallel to the abscissa + #: (index axis) and spanning the length between the point and its + #: subsequent point. + #: connectedhold + #: like "hold" style, but line segments are drawn at each point of the + #: plot to connect the hold lines of the prior point and the current + #: point. Also called a "right angle plot". render_style = Enum("connectedpoints", "hold", "connectedhold") - # Traits UI View for customizing the plot. + #: Traits UI View for customizing the plot. traits_view = View(Item("color", style="custom"), "line_width", "line_style", buttons=["OK", "Cancel"]) diff --git a/chaco/log_mapper.py b/chaco/log_mapper.py index e426a2555..e67a1b293 100644 --- a/chaco/log_mapper.py +++ b/chaco/log_mapper.py @@ -22,7 +22,7 @@ class LogMapper(Base1DMapper): space to a 1-D region in output space. """ - # The value to map when asked to map values <= LOG_MINIMUM to screen space. + #: The value to map when asked to map values <= LOG_MINIMUM to screen space. fill_value = Float(1.0) #------------------------------------------------------------------------ diff --git a/chaco/multi_array_data_source.py b/chaco/multi_array_data_source.py index c7b94bfe2..b4d8bc801 100644 --- a/chaco/multi_array_data_source.py +++ b/chaco/multi_array_data_source.py @@ -29,17 +29,17 @@ class MultiArrayDataSource(AbstractDataSource): # AbstractDataSource traits #------------------------------------------------------------------------ - # The dimensionality of the indices into this data source (overrides - # AbstractDataSource). + #: The dimensionality of the indices into this data source (overrides + #: AbstractDataSource). index_dimension = Int(0) - # The dimensionality of the value at each index point (overrides - # AbstractDataSource). + #: The dimensionality of the value at each index point (overrides + #: AbstractDataSource). value_dimension = Int(1) - # The sort order of the data. - # This is a specialized optimization for 1-D arrays, but it's an important - # one that's used everywhere. + #: The sort order of the data. + #: This is a specialized optimization for 1-D arrays, but it's an important + #: one that's used everywhere. sort_order = SortOrderTrait diff --git a/chaco/multi_line_plot.py b/chaco/multi_line_plot.py index b40b4c050..cbf172486 100644 --- a/chaco/multi_line_plot.py +++ b/chaco/multi_line_plot.py @@ -29,8 +29,8 @@ class MultiLinePlot(BaseXYPlot): stored in a MultiArrayDataSource object. M is the number of lines to be plotted, and N is the number of points in each line. - Constructor Parameters - ---------------------- + Parameters + ---------- index : instance of an ArrayDataSource These are the 'x' or abscissa coordinates. @@ -82,51 +82,51 @@ class MultiLinePlot(BaseXYPlot): """ - # M and N appearing in the comments are as defined in the docstring. + #: M and N appearing in the comments are as defined in the docstring. yindex = Instance(ArrayDataSource) # amplitude = Float(0.0) - # `scale` and `offset` provide a more general transformation, but are currently - # untested. + #: `scale` and `offset` provide a more general transformation, but are currently + #: untested. scale = Float(1.0) offset = Float(0.0) fast_clip = Bool(False) - # The color of the lines. + #: The color of the lines. color = black_color_trait - # A function that returns the color of lines. Overrides `color` if not None. + #: A function that returns the color of lines. Overrides `color` if not None. color_func = Trait(None, None, Callable) - # The color to use to highlight the line when selected. + #: The color to use to highlight the line when selected. selected_color = ColorTrait("lightyellow") - # The style of the selected line. + #: The style of the selected line. selected_line_style = LineStyle("solid") - # The name of the key in self.metadata that holds the selection mask + #: The name of the key in self.metadata that holds the selection mask metadata_name = Str("selections") - # The thickness of the line. + #: The thickness of the line. line_width = Float(1.0) - # The line dash style. + #: The line dash style. line_style = LineStyle use_global_bounds = Bool(True) - # Minimum value in the `value` data source. This must be provided - # in the call to the constructor. + #: Minimum value in the `value` data source. This must be provided + #: in the call to the constructor. global_min = Float - # Maximum value in the `value` data source. This must be provided - # in the call to the constructor. + #: Maximum value in the `value` data source. This must be provided + #: in the call to the constructor. global_max = Float - # Normalized amplitude is the value exposed to the user. + #: Normalized amplitude is the value exposed to the user. normalized_amplitude = Float(-0.5) amplitude_scale = Property(Float, depends_on=['global_min', 'global_max', 'data', diff --git a/chaco/plot.py b/chaco/plot.py index cb4a690b6..35efad966 100644 --- a/chaco/plot.py +++ b/chaco/plot.py @@ -79,29 +79,29 @@ class Plot(DataView): # Data-related traits #------------------------------------------------------------------------ - # The PlotData instance that drives this plot. + #: The PlotData instance that drives this plot. data = Instance(AbstractPlotData) - # Mapping of data names from self.data to their respective datasources. + #: Mapping of data names from self.data to their respective datasources. datasources = Dict(Str, Instance(AbstractDataSource)) #------------------------------------------------------------------------ # General plotting traits #------------------------------------------------------------------------ - # Mapping of plot names to *lists* of plot renderers. + #: Mapping of plot names to *lists* of plot renderers. plots = Dict(Str, List) - # The default index to use when adding new subplots. + #: The default index to use when adding new subplots. default_index = Instance(AbstractDataSource) - # Optional mapper for the color axis. Not instantiated until first use; - # destroyed if no color plots are on the plot. + #: Optional mapper for the color axis. Not instantiated until first use; + #: destroyed if no color plots are on the plot. color_mapper = Instance(AbstractColormap) - # List of colors to cycle through when auto-coloring is requested. Picked - # and ordered to be red-green color-blind friendly, though should not - # be an issue for blue-yellow. + #: List of colors to cycle through when auto-coloring is requested. Picked + #: and ordered to be red-green color-blind friendly, though should not + #: be an issue for blue-yellow. auto_colors = List(["green", "lightgreen", "blue", "lightblue", "red", "pink", "darkgray", "silver"]) @@ -110,9 +110,9 @@ class Plot(DataView): _auto_edge_color_idx = Int(-1) _auto_face_color_idx = Int(-1) - # Mapping of renderer type string to renderer class - # This can be overriden to customize what renderer type the Plot - # will instantiate for its various plotting methods. + #: Mapping of renderer type string to renderer class + #: This can be overriden to customize what renderer type the Plot + #: will instantiate for its various plotting methods. renderer_map = Dict(dict(line = LinePlot, bar = BarPlot, scatter = ScatterPlot, @@ -134,17 +134,17 @@ class Plot(DataView): # Annotations and decorations #------------------------------------------------------------------------ - # The title of the plot. + #: The title of the plot. title = Property() - # The font to use for the title. + #: The font to use for the title. title_font = Property() - # Convenience attribute for title.overlay_position; can be "top", - # "bottom", "left", or "right". + #: Convenience attribute for title.overlay_position; can be "top", + #: "bottom", "left", or "right". title_position = Property() - # Use delegates to expose the other PlotLabel attributes of the plot title + #: Use delegates to expose the other PlotLabel attributes of the plot title title_text = Delegate("_title", prefix="text", modify=True) title_color = Delegate("_title", prefix="color", modify=True) title_angle = Delegate("_title", prefix="angle", modify=True) @@ -152,10 +152,10 @@ class Plot(DataView): # The PlotLabel object that contains the title. _title = Instance(PlotLabel) - # The legend on the plot. + #: The legend on the plot. legend = Instance(Legend) - # Convenience attribute for legend.align; can be "ur", "ul", "ll", "lr". + #: Convenience attribute for legend.align; can be "ur", "ul", "ll", "lr". legend_alignment = Property #------------------------------------------------------------------------ diff --git a/chaco/plot_component.py b/chaco/plot_component.py index 71fc39aad..ac7e375c8 100644 --- a/chaco/plot_component.py +++ b/chaco/plot_component.py @@ -25,32 +25,32 @@ class PlotComponent(Component): # Rendering control traits #------------------------------------------------------------------------ - # The order in which various rendering classes on this component are drawn. - # Note that if this component is placed in a container, in most cases - # the container's draw order is used, since the container calls - # each of its contained components for each rendering pass. - # Typically, the definitions of the layers are: - # - # 1. 'background': Background image, shading - # 2. 'image': A special layer for plots that render as images. This is in - # a separate layer since these plots must all render before non-image - # plots. - # 3. 'underlay': Axes and grids - # 4. 'plot': The main plot area itself - # 5. 'selection': Selected content are rendered above normal plot elements - # to make them stand out - # 6. 'border': Plot borders - # 7. 'annotation': Lines and text that are conceptually part of the "plot" - # but need to be rendered on top of everything else in the plot - # 8. 'overlay': Legends, selection regions, and other tool-drawn visual - # elements + #: The order in which various rendering classes on this component are drawn. + #: Note that if this component is placed in a container, in most cases + #: the container's draw order is used, since the container calls + #: each of its contained components for each rendering pass. + #: Typically, the definitions of the layers are: + #: + #: 1. 'background': Background image, shading + #: 2. 'image': A special layer for plots that render as images. This is in + #: a separate layer since these plots must all render before non-image + #: plots. + #: 3. 'underlay': Axes and grids + #: 4. 'plot': The main plot area itself + #: 5. 'selection': Selected content are rendered above normal plot elements + #: to make them stand out + #: 6. 'border': Plot borders + #: 7. 'annotation': Lines and text that are conceptually part of the "plot" + #: but need to be rendered on top of everything else in the plot + #: 8. 'overlay': Legends, selection regions, and other tool-drawn visual + #: elements draw_order = Instance(list, args=(DEFAULT_DRAWING_ORDER,)) - # The default draw layer for Chaco plot components is the "plot" layer + #: The default draw layer for Chaco plot components is the "plot" layer draw_layer = Str("plot") - # Draw layers in **draw_order**? If False, use _do_draw() (for backwards - # compatibility). + #: Draw layers in **draw_order**? If False, use _do_draw() (for backwards + #: compatibility). use_draw_order = Bool(True) def _use_draw_order_changed(self, old, new): diff --git a/chaco/plot_containers.py b/chaco/plot_containers.py index 974469813..7b0e75f9b 100644 --- a/chaco/plot_containers.py +++ b/chaco/plot_containers.py @@ -46,7 +46,7 @@ class OverlayPlotContainer(BasePlotContainer): draw_order = Instance(list, args=(DEFAULT_DRAWING_ORDER,)) - # Do not use an off-screen backbuffer. + #: Do not use an off-screen backbuffer. use_backbuffer = False # Cache (width, height) of the container's preferred size. @@ -254,13 +254,13 @@ class HPlotContainer(StackedPlotContainer): draw_order = Instance(list, args=(DEFAULT_DRAWING_ORDER,)) - # The order in which components in the plot container are laid out. + #: The order in which components in the plot container are laid out. stack_order = Enum("left_to_right", "right_to_left") - # The amount of space to put between components. + #: The amount of space to put between components. spacing = Float(0.0) - # The vertical alignment of objects that don't span the full height. + #: The vertical alignment of objects that don't span the full height. valign = Enum("bottom", "top", "center") _cached_preferred_size = Tuple @@ -301,22 +301,22 @@ class VPlotContainer(StackedPlotContainer): draw_order = Instance(list, args=(DEFAULT_DRAWING_ORDER,)) - # Overrides StackedPlotContainer. + #: Overrides StackedPlotContainer. stack_dimension = "v" - # Overrides StackedPlotContainer. + #: Overrides StackedPlotContainer. other_dimension = "h" - # Overrides StackedPlotContainer. + #: Overrides StackedPlotContainer. stack_index = 1 # VPlotContainer attributes - # The horizontal alignment of objects that don't span the full width. + #: The horizontal alignment of objects that don't span the full width. halign = Enum("left", "right", "center") - # The order in which components in the plot container are laid out. + #: The order in which components in the plot container are laid out. stack_order = Enum("bottom_to_top", "top_to_bottom") - # The amount of space to put between components. + #: The amount of space to put between components. spacing = Float(0.0) def _do_layout(self): @@ -349,30 +349,30 @@ class GridPlotContainer(BasePlotContainer): draw_order = Instance(list, args=(DEFAULT_DRAWING_ORDER,)) - # The amount of space to put on either side of each component, expressed - # as a tuple (h_spacing, v_spacing). + #: The amount of space to put on either side of each component, expressed + #: as a tuple (h_spacing, v_spacing). spacing = Either(Tuple, List, Array) - # The vertical alignment of objects that don't span the full height. + #: The vertical alignment of objects that don't span the full height. valign = Enum("bottom", "top", "center") - # The horizontal alignment of objects that don't span the full width. + #: The horizontal alignment of objects that don't span the full width. halign = Enum("left", "right", "center") - # The shape of this container, i.e, (rows, columns). The items in - # **components** are shuffled appropriately to match this - # specification. If there are fewer components than cells, the remaining - # cells are filled in with spaces. If there are more components than cells, - # the remainder wrap onto new rows as appropriate. + #: The shape of this container, i.e, (rows, columns). The items in + #: **components** are shuffled appropriately to match this + #: specification. If there are fewer components than cells, the remaining + #: cells are filled in with spaces. If there are more components than cells, + #: the remainder wrap onto new rows as appropriate. shape = Trait((0,0), Either(Tuple, List, Array)) - # This property exposes the underlying grid structure of the container, - # and is the preferred way of setting and reading its contents. - # When read, this property returns a Numpy array with dtype=object; values - # for setting it can be nested tuples, lists, or 2-D arrays. - # The array is in row-major order, so that component_grid[0] is the first - # row, and component_grid[:,0] is the first column. The rows are ordered - # from top to bottom. + #: This property exposes the underlying grid structure of the container, + #: and is the preferred way of setting and reading its contents. + #: When read, this property returns a Numpy array with dtype=object; values + #: for setting it can be nested tuples, lists, or 2-D arrays. + #: The array is in row-major order, so that component_grid[0] is the first + #: row, and component_grid[:,0] is the first column. The rows are ordered + #: from top to bottom. component_grid = Property # The internal component grid, in row-major order. This gets updated diff --git a/chaco/plot_label.py b/chaco/plot_label.py index b608c199a..f835db66e 100644 --- a/chaco/plot_label.py +++ b/chaco/plot_label.py @@ -18,13 +18,13 @@ class PlotLabel(AbstractOverlay): This class wraps a simple Label instance, and delegates some traits to it. """ - # The text of the label. + #: The text of the label. text = LabelDelegate - # The color of the label text. + #: The color of the label text. color = DelegatesTo("_label") - # The font for the label text. + #: The font for the label text. font = LabelDelegate - # The angle of rotation of the label. + #: The angle of rotation of the label. angle = DelegatesTo("_label", "rotate_angle") bgcolor = LabelDelegate @@ -38,21 +38,21 @@ class PlotLabel(AbstractOverlay): # Layout-related traits #------------------------------------------------------------------------ - # Horizontal justification used if the label has more horizontal space - # than it needs. + #: Horizontal justification used if the label has more horizontal space + #: than it needs. hjustify = Enum("center", "left", "right") - # Vertical justification used if the label has more vertical space than it - # needs. + #: Vertical justification used if the label has more vertical space than it + #: needs. vjustify = Enum("center", "bottom", "top") - # The position of this label relative to the object it is overlaying. - # Can be "top", "left", "right", "bottom", and optionally can be preceeded - # by the words "inside" or "outside", separated by a space. If "inside" - # and "outside" are not provided, then defaults to "outside". - # Examples: - # inside top - # outside right + #: The position of this label relative to the object it is overlaying. + #: Can be "top", "left", "right", "bottom", and optionally can be preceeded + #: by the words "inside" or "outside", separated by a space. If "inside" + #: and "outside" are not provided, then defaults to "outside". + #: Examples: + #: inside top + #: outside right overlay_position = Trait("outside top", Str, None) # Should this PlotLabel modify the padding on its underlying component @@ -60,16 +60,16 @@ class PlotLabel(AbstractOverlay): # FIXME: This could cause cycles in layout, so not implemented for now #modify_component = Bool(True) - # By default, this acts like a component and will render on the main - # "plot" layer unless its **component** attribute gets set. + #: By default, this acts like a component and will render on the main + #: "plot" layer unless its **component** attribute gets set. draw_layer = "plot" #------------------------------------------------------------------------ # Private traits #------------------------------------------------------------------------ - # The label has a fixed height and can be resized horizontally. (Overrides - # PlotComponent.) + #: The label has a fixed height and can be resized horizontally. (Overrides + #: PlotComponent.) resizable = "h" # The Label instance this plot label is wrapping. diff --git a/chaco/point_data_source.py b/chaco/point_data_source.py index 170ae66d6..c3f4d9a96 100644 --- a/chaco/point_data_source.py +++ b/chaco/point_data_source.py @@ -26,25 +26,25 @@ class PointDataSource(ArrayDataSource): """ - # The dimensionality of the indices into this data source (overrides - # ArrayDataSource). + #: The dimensionality of the indices into this data source (overrides + #: ArrayDataSource). index_dimension = ReadOnly('scalar') - # The dimensionality of the value at each index point (overrides - # ArrayDataSource). + #: The dimensionality of the value at each index point (overrides + #: ArrayDataSource). value_dimension = ReadOnly('point') - # The sort order of the data. Although sort order is less common with point - # data, it can be useful in case where the value data is sorted along some - # axis. Note that **sort_index** is used only if **sort_order** is not - # 'none'. + #: The sort order of the data. Although sort order is less common with point + #: data, it can be useful in case where the value data is sorted along some + #: axis. Note that **sort_index** is used only if **sort_order** is not + #: 'none'. sort_order = SortOrderTrait - # Which of the value axes the **sort_order** refers to. - # If **sort_order** is 'none', this attribute is ignored. - # In the unlikely event that the value data is sorted along both - # X and Y (i.e., monotonic in both axes), then set **sort_index** to - # whichever one has the best binary-search performance for hit-testing. + #: Which of the value axes the **sort_order** refers to. + #: If **sort_order** is 'none', this attribute is ignored. + #: In the unlikely event that the value data is sorted along both + #: X and Y (i.e., monotonic in both axes), then set **sort_index** to + #: whichever one has the best binary-search performance for hit-testing. sort_index = Enum(0, 1) diff --git a/chaco/polygon_plot.py b/chaco/polygon_plot.py index aec89af41..834b1b0ed 100644 --- a/chaco/polygon_plot.py +++ b/chaco/polygon_plot.py @@ -37,29 +37,29 @@ class PolygonPlot(BaseXYPlot): the line as small as possible while still putting ink on the page. """ - # The color of the line on the edge of the polygon. + #: The color of the line on the edge of the polygon. edge_color = black_color_trait - # The thickness of the edge of the polygon. + #: The thickness of the edge of the polygon. edge_width = Float(1.0) - # The line dash style for the edge of the polygon. + #: The line dash style for the edge of the polygon. edge_style = LineStyle - # The color of the face of the polygon. + #: The color of the face of the polygon. face_color = transparent_color_trait - # Override the hittest_type trait inherited from BaseXYPlot + #: Override the hittest_type trait inherited from BaseXYPlot hittest_type = Enum("poly", "point", "line") - # The RGBA tuple for rendering edges. It is always a tuple of length 4. - # It has the same RGB values as edge_color_, and its alpha value is the - # alpha value of self.edge_color multiplied by self.alpha. + #: The RGBA tuple for rendering edges. It is always a tuple of length 4. + #: It has the same RGB values as edge_color_, and its alpha value is the + #: alpha value of self.edge_color multiplied by self.alpha. effective_edge_color = Property(Tuple, depends_on=['edge_color', 'alpha']) - # The RGBA tuple for rendering the face. It is always a tuple of length 4. - # It has the same RGB values as face_color_, and its alpha value is the - # alpha value of self.face_color multiplied by self.alpha. + #: The RGBA tuple for rendering the face. It is always a tuple of length 4. + #: It has the same RGB values as face_color_, and its alpha value is the + #: alpha value of self.face_color multiplied by self.alpha. effective_face_color = Property(Tuple, depends_on=['face_color', 'alpha']) #---------------------------------------------------------------------- diff --git a/chaco/quiverplot.py b/chaco/quiverplot.py index adf614741..7b5d4c52e 100644 --- a/chaco/quiverplot.py +++ b/chaco/quiverplot.py @@ -13,29 +13,29 @@ class QuiverPlot(ScatterPlot): - # Determines how to interpret the data in the **vectors** data source. - # "vector": each tuple is a (dx, dy) - # "radial": each tuple is an (r, theta) + #: Determines how to interpret the data in the **vectors** data source. + #: "vector": each tuple is a (dx, dy) + #: "radial": each tuple is an (r, theta) data_type = Enum("vector", "radial") # TODO: implement "radial" - # A datasource that returns an Nx2 array array indicating directions - # of the vectors. The interpretation of this array is dependent on - # the setting of the **data_type** attribute. - # - # Usually this will be a MultiArrayDataSource. + #: A datasource that returns an Nx2 array array indicating directions + #: of the vectors. The interpretation of this array is dependent on + #: the setting of the **data_type** attribute. + #: + #: Usually this will be a MultiArrayDataSource. vectors = Instance(AbstractDataSource) #------------------------------------------------------------------------ # Visual attributes of the vector #------------------------------------------------------------------------ - # The color of the lines + #: The color of the lines line_color = ColorTrait("black") - # The width of the lines + #: The width of the lines line_width = Float(1.0) - # The length, in pixels, of the arrowhead + #: The length, in pixels, of the arrowhead arrow_size = Int(5) #------------------------------------------------------------------------ diff --git a/chaco/scatter_inspector_overlay.py b/chaco/scatter_inspector_overlay.py index 60297fbda..817c229c6 100644 --- a/chaco/scatter_inspector_overlay.py +++ b/chaco/scatter_inspector_overlay.py @@ -21,7 +21,7 @@ class ScatterInspectorOverlay(AbstractOverlay): Used in conjuction with ScatterInspector. """ - # The style to use when a point is hovered over + #: The style to use when a point is hovered over hover_metadata_name = Str('hover') hover_marker = Trait(None, None, MarkerTrait) hover_marker_size = Trait(None, None, Int) @@ -29,7 +29,7 @@ class ScatterInspectorOverlay(AbstractOverlay): hover_color = Trait(None, None, ColorTrait) hover_outline_color = Trait(None, None, ColorTrait) - # The style to use when a point has been selected by a click + #: The style to use when a point has been selected by a click selection_metadata_name = Str('selections') selection_marker = Trait(None, None, MarkerTrait) selection_marker_size = Trait(None, None, Int) diff --git a/chaco/selectable_overlay_container.py b/chaco/selectable_overlay_container.py index 6eb979b44..db71dfb1c 100644 --- a/chaco/selectable_overlay_container.py +++ b/chaco/selectable_overlay_container.py @@ -17,21 +17,21 @@ class SelectableOverlayPlotContainer(OverlayPlotContainer): An OverlayPlotContainer that can show a selection region on top of it. """ - # Screen position of the start of the selection, which can be in the x- or - # y-dimension, depending on **selection_direction**. + #: Screen position of the start of the selection, which can be in the x- or + #: y-dimension, depending on **selection_direction**. selection_screen_start = Float(0.0) - # Screen position of the end of the selection, which can be in the x- or - # y-dimension, depending on **selection_direction**. + #: Screen position of the end of the selection, which can be in the x- or + #: y-dimension, depending on **selection_direction**. selection_screen_end = Float(0.0) - # Is there an active selection? + #: Is there an active selection? selection_active = Bool(False) - # The direction of the selection. + #: The direction of the selection. selection_direction = Enum('v', 'h') - # The color to use to fill the selected region. + #: The color to use to fill the selected region. selection_fill_color = ColorTrait('lightskyblue') - # The color to use to draw the border of the selected region. + #: The color to use to draw the border of the selected region. selection_border_color = ColorTrait('dodgerblue') - # The transparency of the **selection_fill_color**. + #: The transparency of the **selection_fill_color**. selection_alpha = Float(0.3) def _draw_overlays(self, gc, view_bounds=None, mode='normal'): diff --git a/chaco/simple_plot_frame.py b/chaco/simple_plot_frame.py index 5f19c6644..cae400b47 100644 --- a/chaco/simple_plot_frame.py +++ b/chaco/simple_plot_frame.py @@ -26,18 +26,18 @@ class SimplePlotFrame(BasePlotFrame): This class will be removed sometime in the future. """ - # This frame has only one position for plot components. Overrides - # PlotFrame. + #: This frame has only one position for plot components. Overrides + #: PlotFrame. slot_names = ("center") - # Default width and height. Class attribute. + #: Default width and height. Class attribute. default_bounds = (500, 500) - # This frame does not resize to fit components. Overrides PlotFrame. + #: This frame does not resize to fit components. Overrides PlotFrame. fit_components = "" - # This frame maximizes itself within the window, if it is a top-level - # component. Overrides Enable Container. + #: This frame maximizes itself within the window, if it is a top-level + #: component. Overrides Enable Container. fit_window = True #------------------------------------------------------------------------ diff --git a/chaco/text_box_overlay.py b/chaco/text_box_overlay.py index 3e9dcd09d..bf3f3b842 100644 --- a/chaco/text_box_overlay.py +++ b/chaco/text_box_overlay.py @@ -18,49 +18,49 @@ class TextBoxOverlay(AbstractOverlay): #### Configuration traits ################################################# - # The text to display in the box. + #: The text to display in the box. text = Str - # The font to use for the text. + #: The font to use for the text. font = KivaFont("modern 12") - # The background color for the box (overrides AbstractOverlay). + #: The background color for the box (overrides AbstractOverlay). bgcolor = ColorTrait("transparent") - # The alpha value to apply to **bgcolor** + #: The alpha value to apply to **bgcolor** alpha = Trait(1.0, None, Float) - # The color of the outside box. + #: The color of the outside box. border_color = ColorTrait("dodgerblue") - # The color of the text. + #: The color of the text. text_color = ColorTrait("black") - # The thickness of box border. + #: The thickness of box border. border_size = Int(1) - # The border visibility. Defaults to true to duplicate previous behavior. + #: The border visibility. Defaults to true to duplicate previous behavior. border_visible = Bool(True) - # Number of pixels of padding around the text within the box. + #: Number of pixels of padding around the text within the box. padding = Int(5) - # The maximum width of the displayed text. This affects the width of the - # text only, not the text box, which includes margins around the text and - # `padding`. - # A `max_text_width` of 0.0 means that the width will not be restricted. + #: The maximum width of the displayed text. This affects the width of the + #: text only, not the text box, which includes margins around the text and + #: `padding`. + #: A `max_text_width` of 0.0 means that the width will not be restricted. max_text_width = Float(0.0) - # Alignment of the text in the box: - # - # * "ur": upper right - # * "ul": upper left - # * "ll": lower left - # * "lr": lower right + #: Alignment of the text in the box: + #: + #: * "ur": upper right + #: * "ul": upper left + #: * "ll": lower left + #: * "lr": lower right align = Enum("ur", "ul", "ll", "lr") - # This allows subclasses to specify an alternate position for the root - # of the text box. Must be a sequence of length 2. + #: This allows subclasses to specify an alternate position for the root + #: of the text box. Must be a sequence of length 2. alternate_position = Any #### Public 'AbstractOverlay' interface ################################### diff --git a/chaco/toolbar_plot.py b/chaco/toolbar_plot.py index b161233d8..bb26b2ad1 100644 --- a/chaco/toolbar_plot.py +++ b/chaco/toolbar_plot.py @@ -4,7 +4,7 @@ on_trait_change class ToolbarPlot(Plot): - # Should we turn on the auto-hide feature on the toolbar? + #: Should we turn on the auto-hide feature on the toolbar? auto_hide = DelegatesTo('toolbar') toolbar = Instance(PlotToolbar) @@ -12,11 +12,11 @@ class ToolbarPlot(Plot): toolbar_class = Type(PlotToolbar) toolbar_added = False - # Location of the default toolbar that is created if a toolbar - # is not specified with the `toolbar` attribute. Changing this - # attribute after the ToolbarPlot instance is created has no effect; - # use obj.toolbar.location to dynamically change the location of the - # instance `obj`s toolbar. + #: Location of the default toolbar that is created if a toolbar + #: is not specified with the `toolbar` attribute. Changing this + #: attribute after the ToolbarPlot instance is created has no effect; + #: use obj.toolbar.location to dynamically change the location of the + #: instance `obj`s toolbar. toolbar_location = Enum('top', 'right', 'bottom', 'left') def __init__(self, *args, **kw): diff --git a/chaco/tools/better_selecting_zoom.py b/chaco/tools/better_selecting_zoom.py index 8aa449a1f..86d7e4a5f 100644 --- a/chaco/tools/better_selecting_zoom.py +++ b/chaco/tools/better_selecting_zoom.py @@ -15,28 +15,28 @@ class BetterSelectingZoom(AbstractOverlay, BetterZoom): desired region to zoom in to """ - # The selection mode: - # - # range: - # Select a range across a single index or value axis. - # box: - # Perform a "box" selection on two axes. + #: The selection mode: + #: + #: range: + #: Select a range across a single index or value axis. + #: box: + #: Perform a "box" selection on two axes. tool_mode = Enum("box", "range") - # Is the tool always "on"? If True, left-clicking always initiates - # a zoom operation; if False, the user must press a key to enter zoom mode. + #: Is the tool always "on"? If True, left-clicking always initiates + #: a zoom operation; if False, the user must press a key to enter zoom mode. always_on = Bool(False) - # Defines a meta-key, that works with always_on to set the zoom mode. This - # is useful when the zoom tool is used in conjunction with the pan tool. + #: Defines a meta-key, that works with always_on to set the zoom mode. This + #: is useful when the zoom tool is used in conjunction with the pan tool. always_on_modifier = Enum('control', 'shift', 'control', 'alt') - # The mouse button that initiates the drag. If "None", then the tool - # will not respond to drag. (It can still respond to mousewheel events.) + #: The mouse button that initiates the drag. If "None", then the tool + #: will not respond to drag. (It can still respond to mousewheel events.) drag_button = Enum("left", "right", None) - # The minimum amount of screen space the user must select in order for - # the tool to actually take effect. + #: The minimum amount of screen space the user must select in order for + #: the tool to actually take effect. minimum_screen_delta = Int(10) @@ -45,18 +45,18 @@ class BetterSelectingZoom(AbstractOverlay, BetterZoom): # SimpleZoom #------------------------------------------------------------------------- - # Conversion ratio from wheel steps to zoom factors. + #: Conversion ratio from wheel steps to zoom factors. wheel_zoom_step = Property(Float, depends_on='zoom_factor') - # The key press to enter zoom mode, if **always_on** is False. Has no effect - # if **always_on** is True. + #: The key press to enter zoom mode, if **always_on** is False. Has no effect + #: if **always_on** is True. enter_zoom_key = Instance(KeySpec, args=("z",)) - # The key press to leave zoom mode, if **always_on** is False. Has no effect - # if **always_on** is True. + #: The key press to leave zoom mode, if **always_on** is False. Has no effect + #: if **always_on** is True. exit_zoom_key = Instance(KeySpec, args=("z",)) - # Disable the tool after the zoom is completed? + #: Disable the tool after the zoom is completed? disable_on_complete = Property() @@ -64,27 +64,27 @@ class BetterSelectingZoom(AbstractOverlay, BetterZoom): # Appearance properties (for Box mode) #------------------------------------------------------------------------- - # The pointer to use when drawing a zoom box. + #: The pointer to use when drawing a zoom box. pointer = "magnifier" - # The color of the selection box. + #: The color of the selection box. color = ColorTrait("lightskyblue") - # The alpha value to apply to **color** when filling in the selection - # region. Because it is almost certainly useless to have an opaque zoom - # rectangle, but it's also extremely useful to be able to use the normal - # named colors from Enable, this attribute allows the specification of a - # separate alpha value that replaces the alpha value of **color** at draw - # time. + #: The alpha value to apply to **color** when filling in the selection + #: region. Because it is almost certainly useless to have an opaque zoom + #: rectangle, but it's also extremely useful to be able to use the normal + #: named colors from Enable, this attribute allows the specification of a + #: separate alpha value that replaces the alpha value of **color** at draw + #: time. alpha = Trait(0.4, None, Float) - # The color of the outside selection rectangle. + #: The color of the outside selection rectangle. border_color = ColorTrait("dodgerblue") - # The thickness of selection rectangle border. + #: The thickness of selection rectangle border. border_size = Int(1) - # The possible event states of this zoom tool. + #: The possible event states of this zoom tool. event_state = Enum("normal", "selecting", "pre_selecting") # The (x,y) screen point where the mouse went down. diff --git a/chaco/tools/better_zoom.py b/chaco/tools/better_zoom.py index faa0dfed1..1ee6a53d0 100644 --- a/chaco/tools/better_zoom.py +++ b/chaco/tools/better_zoom.py @@ -19,53 +19,53 @@ class BetterZoom(BaseTool, ToolHistoryMixin): - # Keys to zoom in/out + #: Keys to zoom in/out zoom_in_key = Instance(KeySpec, args=("+",), kw={'ignore': ['shift']}) zoom_out_key = Instance(KeySpec, args=("-",)) - # Keys to zoom in/out in x direction only + #: Keys to zoom in/out in x direction only zoom_in_x_key = Instance(KeySpec, args=("Right", "shift")) zoom_out_x_key = Instance(KeySpec, args=("Left", "shift")) - # Keys to zoom in/out in y direction only + #: Keys to zoom in/out in y direction only zoom_in_y_key = Instance(KeySpec, args=("Up", "shift")) zoom_out_y_key = Instance(KeySpec, args=("Down", "shift")) - # Key to go to the previous state in the history. + #: Key to go to the previous state in the history. prev_state_key = Instance(KeySpec, args=("z", "control")) - # Key to go to the next state in the history. + #: Key to go to the next state in the history. next_state_key = Instance(KeySpec, args=("y", "control")) - # Enable the mousewheel for zooming? + #: Enable the mousewheel for zooming? enable_wheel = Bool(True) - # if the mouse pointer should be used to control the center - # of the zoom action + #: if the mouse pointer should be used to control the center + #: of the zoom action zoom_to_mouse = Bool(True) - # if the mouse pointer should be used to control the center - # of the zoom action even for key events based zoom + #: if the mouse pointer should be used to control the center + #: of the zoom action even for key events based zoom keys_zoom_to_mouse = Bool(True) - # The axis to which the selection made by this tool is perpendicular. This - # only applies in 'range' mode. + #: The axis to which the selection made by this tool is perpendicular. This + #: only applies in 'range' mode. axis = Enum("both", "index", "value") - # The maximum ratio between the original data space bounds and the - # zoomed-in data space bounds. If No limit is desired, set to inf + #: The maximum ratio between the original data space bounds and the + #: zoomed-in data space bounds. If No limit is desired, set to inf x_max_zoom_factor = Float(1e5) y_max_zoom_factor = Float(1e5) - # The maximum ratio between the zoomed-out data space bounds and the - # original bounds. If No limit is desired, set to -inf + #: The maximum ratio between the zoomed-out data space bounds and the + #: original bounds. If No limit is desired, set to -inf x_min_zoom_factor = Float(1e-5) y_min_zoom_factor = Float(1e-5) - # The amount to zoom in by. The zoom out will be inversely proportional + #: The amount to zoom in by. The zoom out will be inversely proportional zoom_factor = Float(2.0) - #: the position to zoom on (usually the mouse location) + #:: the position to zoom on (usually the mouse location) position = Tuple(Float, Float) # The zoom factor on each axis diff --git a/chaco/tools/broadcaster.py b/chaco/tools/broadcaster.py index 28d90fbb0..53ebc0065 100644 --- a/chaco/tools/broadcaster.py +++ b/chaco/tools/broadcaster.py @@ -8,11 +8,11 @@ class BroadcasterTool(BaseTool): receives to all of the tools. """ - # The tools to which this tool broadcasts events. + #: The tools to which this tool broadcasts events. tools = List - # Mapping from tools to transforms, for tools that can be mouse owners. - # (See enable.AbstractWindow.) + #: Mapping from tools to transforms, for tools that can be mouse owners. + #: (See enable.AbstractWindow.) mouse_owners = Dict def dispatch(self, event, suffix): diff --git a/chaco/tools/data_label_tool.py b/chaco/tools/data_label_tool.py index 1235926aa..938049a68 100644 --- a/chaco/tools/data_label_tool.py +++ b/chaco/tools/data_label_tool.py @@ -15,11 +15,11 @@ class DataLabelTool(DragTool): to the DataLabel. """ - # The mouse button that initiates the drag. + #: The mouse button that initiates the drag. drag_button = Enum("left", "right") - # Use the root of the label's arrow (if any) as the closest corner of the - # label? + #: Use the root of the label's arrow (if any) as the closest corner of the + #: label? auto_arrow_root = Bool(True) # The original position of the label with respect to the data point. diff --git a/chaco/tools/dataprinter.py b/chaco/tools/dataprinter.py index 141c9e825..0903b0d66 100644 --- a/chaco/tools/dataprinter.py +++ b/chaco/tools/dataprinter.py @@ -16,13 +16,13 @@ class DataPrinter(BaseTool): point under the cursor. """ - # This tool is a listener, and does not display anything (overrides BaseTool). + #: This tool is a listener, and does not display anything (overrides BaseTool). visible = False - # Turn off drawing, because the tool prints to stdout. + #: Turn off drawing, because the tool prints to stdout. draw_mode = "none" - # The string to format the (x,y) value in data space. + #: The string to format the (x,y) value in data space. format = Str("(%.3f, %.3f)") def normal_mouse_move(self, event): diff --git a/chaco/tools/drag_zoom.py b/chaco/tools/drag_zoom.py index 1a7e09eac..c0039e199 100644 --- a/chaco/tools/drag_zoom.py +++ b/chaco/tools/drag_zoom.py @@ -28,24 +28,24 @@ class DragZoom(DragTool, BetterZoom): of the axis mappers. """ - # The mouse button that initiates the drag + #: The mouse button that initiates the drag drag_button = Enum("left", "right", "middle") - # Scaling factor on the zoom "speed". A speed of 1.0 implies a zoom rate of - # 5% for every 10 pixels. + #: Scaling factor on the zoom "speed". A speed of 1.0 implies a zoom rate of + #: 5% for every 10 pixels. speed = Float(1.0) - # Whether or not to preserve the aspect ratio of X to Y while zooming in. - # (See class docstring for more info.) + #: Whether or not to preserve the aspect ratio of X to Y while zooming in. + #: (See class docstring for more info.) maintain_aspect_ratio = Bool(True) - # The pointer to use when we're in the act of zooming + #: The pointer to use when we're in the act of zooming drag_pointer = "magnifier" - # Whether or not to zoom in one axis only + #: Whether or not to zoom in one axis only single_axis = Bool(False) - # Whether to restrict zoom to the domain of the mappers + #: Whether to restrict zoom to the domain of the mappers restrict_domain = Bool(False) zoom_to_mouse = Bool(False) diff --git a/chaco/tools/draw_points_tool.py b/chaco/tools/draw_points_tool.py index 615508398..00ecbdf61 100644 --- a/chaco/tools/draw_points_tool.py +++ b/chaco/tools/draw_points_tool.py @@ -15,11 +15,11 @@ class DrawPointsTool(BaseTool): """ A tool that draws points onto a rectangular plot as they are clicked. """ - # A data source for the x-dimension of the drawn points. + #: A data source for the x-dimension of the drawn points. xdata = Instance(ArrayDataSource) - # A data source for the y-dimension of the drawn points. + #: A data source for the y-dimension of the drawn points. ydata = Instance(ArrayDataSource) - # Is this the active tool? + #: Is this the active tool? activated = Bool(True) #It would be nice to set the pointer to a cross diff --git a/chaco/tools/highlight_tool.py b/chaco/tools/highlight_tool.py index adc4f11c7..e6cba592a 100644 --- a/chaco/tools/highlight_tool.py +++ b/chaco/tools/highlight_tool.py @@ -16,23 +16,23 @@ class HighlightTool(BaseTool): graph by clicking on it. """ - # The name of the data source metadata which controls selections. + #: The name of the data source metadata which controls selections. metadata_name = Str('selections') - # The mouse button that initiates the selection. + #: The mouse button that initiates the selection. drag_button = Enum("left", "right") - # Threshold distance for hit-testing. + #: Threshold distance for hit-testing. threshold = Float(20.0) #--------------------------------------------------------------------- # Inherited BaseTool traits #--------------------------------------------------------------------- - # This tool is not drawn. Overrides BaseTool. + #: This tool is not drawn. Overrides BaseTool. draw_mode = "none" - # This tool is not visible. Overrides BaseTool. + #: This tool is not visible. Overrides BaseTool. visible = False def normal_left_down(self, event): diff --git a/chaco/tools/image_inspector_tool.py b/chaco/tools/image_inspector_tool.py index f13c58ebd..aa6bba016 100644 --- a/chaco/tools/image_inspector_tool.py +++ b/chaco/tools/image_inspector_tool.py @@ -13,20 +13,20 @@ class ImageInspectorTool(BaseTool): """ A tool that captures the color and underlying values of an image plot. """ - # This event fires whenever the mouse moves over a new image point. - # Its value is a dict with a key "color_value", and possibly a key - # "data_value" if the plot is a color-mapped image plot. + #: This event fires whenever the mouse moves over a new image point. + #: Its value is a dict with a key "color_value", and possibly a key + #: "data_value" if the plot is a color-mapped image plot. new_value = Event - # Indicates whether overlays listening to this tool should be visible. + #: Indicates whether overlays listening to this tool should be visible. visible = Bool(True) - # Stores the last mouse position. This can be used by overlays to - # position themselves around the mouse. + #: Stores the last mouse position. This can be used by overlays to + #: position themselves around the mouse. last_mouse_position = Tuple - # This key will show and hide any ImageInspectorOverlays associated - # with this tool. + #: This key will show and hide any ImageInspectorOverlays associated + #: with this tool. inspector_key = KeySpec('p') # Stores the value of self.visible when the mouse leaves the tool, @@ -85,19 +85,19 @@ class ImageInspectorOverlay(TextBoxOverlay): """ An overlay that displays a box containing values from an ImageInspectorTool instance. """ - # An instance of ImageInspectorTool; this overlay listens to the tool - # for changes, and updates its displayed text accordingly. + #: An instance of ImageInspectorTool; this overlay listens to the tool + #: for changes, and updates its displayed text accordingly. image_inspector = Any - # Anchor the text to the mouse? (If False, then the text is in one of the - # corners.) Use the **align** trait to determine which corner. + #: Anchor the text to the mouse? (If False, then the text is in one of the + #: corners.) Use the **align** trait to determine which corner. tooltip_mode = Bool(False) - # The default state of the overlay is invisible (overrides PlotComponent). + #: The default state of the overlay is invisible (overrides PlotComponent). visible = False - # Whether the overlay should auto-hide and auto-show based on the - # tool's location, or whether it should be forced to be hidden or visible. + #: Whether the overlay should auto-hide and auto-show based on the + #: tool's location, or whether it should be forced to be hidden or visible. visibility = Enum("auto", True, False) def _image_inspector_changed(self, old, new): diff --git a/chaco/tools/lasso_selection.py b/chaco/tools/lasso_selection.py index 053eb863d..a69ec5122 100644 --- a/chaco/tools/lasso_selection.py +++ b/chaco/tools/lasso_selection.py @@ -21,58 +21,58 @@ class LassoSelection(AbstractController): "Lassoing" means drawing an arbitrary selection region around the points by dragging the mouse along the outline of the region. """ - # An Nx2 array of points in data space representing all selected points. + #: An Nx2 array of points in data space representing all selected points. dataspace_points = Property(Array) - # A list of all the selection polygons. + #: A list of all the selection polygons. disjoint_selections = Property(List) - # Fires whenever **dataspace_points** changes, necessitating a redraw of the - # selection region. + #: Fires whenever **dataspace_points** changes, necessitating a redraw of the + #: selection region. updated = Event - # Fires when the selection mask changes. + #: Fires when the selection mask changes. selection_changed = Event - # Fires when the user release the mouse button and finalizes the selection. + #: Fires when the user release the mouse button and finalizes the selection. selection_completed = Event - # If True, the selection mask is updated as the mouse moves, rather - # than only at the beginning and end of the selection operation. + #: If True, the selection mask is updated as the mouse moves, rather + #: than only at the beginning and end of the selection operation. incremental_select = Bool(False) - # The selection mode of the lasso pointer: "include", "exclude" or - # "invert" points from the selection. The "include" and "exclude" - # settings essentially invert the selection mask. The "invert" setting - # differs from "exclude" in that "invert" inverses the selection of all - # points the the lasso'ed polygon, while "exclude" operates only on - # points included in a previous selection. + #: The selection mode of the lasso pointer: "include", "exclude" or + #: "invert" points from the selection. The "include" and "exclude" + #: settings essentially invert the selection mask. The "invert" setting + #: differs from "exclude" in that "invert" inverses the selection of all + #: points the the lasso'ed polygon, while "exclude" operates only on + #: points included in a previous selection. selection_mode = Enum("include", "exclude", "invert") - # The data source that the mask of selected points is attached to. Note - # that the indices in this data source must match the indices of the data - # in the plot. + #: The data source that the mask of selected points is attached to. Note + #: that the indices in this data source must match the indices of the data + #: in the plot. selection_datasource = Instance(AbstractDataSource) - # The name of the metadata on the datasource that we will write - # the selection mask to + #: The name of the metadata on the datasource that we will write + #: the selection mask to metadata_name = Str("selection") - # Mapping from screen space to data space. By default, it is just - # self.component. + #: Mapping from screen space to data space. By default, it is just + #: self.component. plot = Property - # The button which this tool responds to + #: The button which this tool responds to drag_button = Enum("left", "right") - # The possible event states of this selection tool (overrides - # enable.Interactor). - # - # normal: - # Nothing has been selected, and the user is not dragging the mouse. - # selecting: - # The user is dragging the mouse and is actively changing the - # selection region. + #: The possible event states of this selection tool (overrides + #: enable.Interactor). + #: + #: normal: + #: Nothing has been selected, and the user is not dragging the mouse. + #: selecting: + #: The user is dragging the mouse and is actively changing the + #: selection region. event_state = Enum('normal', 'selecting') #---------------------------------------------------------------------- diff --git a/chaco/tools/legend_tool.py b/chaco/tools/legend_tool.py index ef41febe7..527dbb728 100644 --- a/chaco/tools/legend_tool.py +++ b/chaco/tools/legend_tool.py @@ -13,11 +13,11 @@ class LegendTool(DragTool): to the legend. """ - # The mouse button that initiates the drag. + #: The mouse button that initiates the drag. drag_button = Enum("left", "right") - # Whether to change the legend's **align** property in accord with - # the quadrant into which it is dropped. + #: Whether to change the legend's **align** property in accord with + #: the quadrant into which it is dropped. auto_align = Bool(True) diff --git a/chaco/tools/line_inspector.py b/chaco/tools/line_inspector.py index 12eef8449..2ae7c9be7 100644 --- a/chaco/tools/line_inspector.py +++ b/chaco/tools/line_inspector.py @@ -17,47 +17,47 @@ class LineInspector(BaseTool): This tool supports only plots with a 1-D index. """ - # The axis that this tool is parallel to. + #: The axis that this tool is parallel to. axis = Enum("index", "value", "index_x", "index_y") - # The possible inspection modes of the tool. - # - # space: - # The tool maps from screen space into the data space of the plot. - # indexed: - # The tool maps from screen space to an index into the plot's index array. + #: The possible inspection modes of the tool. + #: + #: space: + #: The tool maps from screen space into the data space of the plot. + #: indexed: + #: The tool maps from screen space to an index into the plot's index array. inspect_mode = Enum("space", "indexed") - # Respond to user mouse events? + #: Respond to user mouse events? is_interactive = Bool(True) - # Does the tool respond to updates in the metadata on the data source - # and update its own position? + #: Does the tool respond to updates in the metadata on the data source + #: and update its own position? is_listener = Bool(False) - # If interactive, does the line inspector write the current data space point - # to the appropriate data source's metadata? + #: If interactive, does the line inspector write the current data space point + #: to the appropriate data source's metadata? write_metadata = Bool(False) - # The name of the metadata field to listen or write to. + #: The name of the metadata field to listen or write to. metadata_name = Str("selections") #------------------------------------------------------------------------ # Override default values of inherited traits in BaseTool #------------------------------------------------------------------------ - # This tool is visible (overrides BaseTool). + #: This tool is visible (overrides BaseTool). visible = True - # This tool is drawn as an overlay (overrides BaseTool). + #: This tool is drawn as an overlay (overrides BaseTool). draw_mode = "overlay" # TODO:STYLE - # Color of the line. + #: Color of the line. color = ColorTrait("black") - # Width in pixels of the line. + #: Width in pixels of the line. line_width = Float(1.0) - # Dash style of the line. + #: Dash style of the line. line_style = LineStyle("solid") # Last recorded position of the mouse diff --git a/chaco/tools/line_segment_tool.py b/chaco/tools/line_segment_tool.py index 37d7c5f2b..34913dd89 100644 --- a/chaco/tools/line_segment_tool.py +++ b/chaco/tools/line_segment_tool.py @@ -19,33 +19,33 @@ class LineSegmentTool(AbstractOverlay): series of points connected by lines. """ - # The component that this tool overlays + #: The component that this tool overlays component = Instance(Component) - # The current line segment being drawn. + #: The current line segment being drawn. line = Instance(Line, args=()) - # A list of the points in data space as (index,value) + #: A list of the points in data space as (index,value) points = List - # The event states are: - # - # normal: - # The user may have selected points, and is moving the cursor around. - # selecting: - # The user has clicked down but hasn't let go of the button yet, - # and can still drag the point around. - # dragging: - # The user has clicked on an existing point and is dragging it - # around. When the user releases the mouse button, the tool returns - # to the "normal" state + #: The event states are: + #: + #: normal: + #: The user may have selected points, and is moving the cursor around. + #: selecting: + #: The user has clicked down but hasn't let go of the button yet, + #: and can still drag the point around. + #: dragging: + #: The user has clicked on an existing point and is dragging it + #: around. When the user releases the mouse button, the tool returns + #: to the "normal" state event_state = Enum("normal", "selecting", "dragging") - # The pixel distance from a vertex that is considered 'on' the vertex. + #: The pixel distance from a vertex that is considered 'on' the vertex. proximity_distance = Int(4) - # The data (index, value) position of the mouse cursor; this is used by various - # draw() routines. + #: The data (index, value) position of the mouse cursor; this is used by various + #: draw() routines. mouse_position = Trait(None, None, Tuple) # The index of the vertex being dragged, if any. @@ -63,13 +63,13 @@ class LineSegmentTool(AbstractOverlay): # The cursor shapes to use for various modes - # Cursor shape for non-tool use. + #: Cursor shape for non-tool use. original_cursor = Pointer("arrow") - # Cursor shape for drawing. + #: Cursor shape for drawing. normal_cursor = Pointer("pencil") - # Cursor shape for deleting points. + #: Cursor shape for deleting points. delete_cursor = Pointer("bullseye") - # Cursor shape for moving points. + #: Cursor shape for moving points. move_cursor = Pointer("sizing") @@ -77,7 +77,7 @@ class LineSegmentTool(AbstractOverlay): # Traits inherited from Component #------------------------------------------------------------------------ - # The tool is initially invisible, because there is nothing to draw. + #: The tool is initially invisible, because there is nothing to draw. visible = Bool(False) #------------------------------------------------------------------------ diff --git a/chaco/tools/pan_tool.py b/chaco/tools/pan_tool.py index 9543de629..f54655e03 100644 --- a/chaco/tools/pan_tool.py +++ b/chaco/tools/pan_tool.py @@ -13,42 +13,42 @@ class PanTool(BaseTool): button and dragging. """ - # The mouse button that initiates the drag operation. + #: The mouse button that initiates the drag operation. drag_button = Enum("left", "middle", "right") - # The cursor to use when panning. + #: The cursor to use when panning. drag_pointer = Pointer("hand") - # Scaling factor on the panning "speed". + #: Scaling factor on the panning "speed". speed = Float(1.0) - # The modifier key that, if depressed when the drag is initiated, constrains - # the panning to happen in the only direction of largest initial motion. - # It is possible to permanently restrict this tool to always drag along one - # direction. To do so, set constrain=True, constrain_key=None, and - # constrain_direction to the desired direction. + #: The modifier key that, if depressed when the drag is initiated, constrains + #: the panning to happen in the only direction of largest initial motion. + #: It is possible to permanently restrict this tool to always drag along one + #: direction. To do so, set constrain=True, constrain_key=None, and + #: constrain_direction to the desired direction. constrain_key = Enum(None, "shift", "control", "alt") - # Keys to Pan via keyboard + #: Keys to Pan via keyboard pan_right_key = Instance(KeySpec, args=("Right",)) pan_left_key = Instance(KeySpec, args=("Left",)) pan_up_key = Instance(KeySpec, args=("Up",)) pan_down_key = Instance(KeySpec, args=("Down",)) - # number of pixels the keys should pan - # disabled if 0.0 + #: number of pixels the keys should pan + #: disabled if 0.0 pan_keys_step = Float(0.0) - # Constrain the panning to one direction? + #: Constrain the panning to one direction? constrain = Bool(False) - # The direction of constrained draw. A value of None means that the user - # has initiated the drag and pressed the constrain_key, but hasn't moved - # the mouse yet; the magnitude of the components of the next mouse_move - # event will determine the constrain_direction. + #: The direction of constrained draw. A value of None means that the user + #: has initiated the drag and pressed the constrain_key, but hasn't moved + #: the mouse yet; the magnitude of the components of the next mouse_move + #: event will determine the constrain_direction. constrain_direction = Enum(None, "x", "y") - # Restrict to the bounds of the plot data + #: Restrict to the bounds of the plot data restrict_to_data = Bool(False) # (x,y) of the point where the mouse button was pressed. @@ -67,14 +67,14 @@ class PanTool(BaseTool): # Inherited BaseTool traits #------------------------------------------------------------------------ - # The tool does not have a visual representation (overrides - # BaseTool). + #: The tool does not have a visual representation (overrides + #: BaseTool). draw_mode = "none" - # The tool is not visible (overrides BaseTool). + #: The tool is not visible (overrides BaseTool). visible = False - # The possible event states of this tool (overrides enable.Interactor). + #: The possible event states of this tool (overrides enable.Interactor). event_state = Enum("normal", "panning") def normal_key_pressed(self, event): diff --git a/chaco/tools/point_marker.py b/chaco/tools/point_marker.py index fe6b0ff37..580e90ca5 100755 --- a/chaco/tools/point_marker.py +++ b/chaco/tools/point_marker.py @@ -15,19 +15,19 @@ class PointMarker(BaseTool): line corresponding to the index indicated by the "selections" metadata. """ - # The axis that this tool is parallel to. + #: The axis that this tool is parallel to. axis = Enum("index", "value") - # This tool is visible (overrides BaseTool). + #: This tool is visible (overrides BaseTool). visible = True - # This tool is drawn as an overlay (overrides BaseTool). + #: This tool is drawn as an overlay (overrides BaseTool). draw_mode = "overlay" # TODO:STYLE - # The color of the line. + #: The color of the line. color = ColorTrait("red") - # The width of the line, in pixels. + #: The width of the line, in pixels. line_width = Float(1.0) def draw(self, gc, view_bounds=None): diff --git a/chaco/tools/range_selection.py b/chaco/tools/range_selection.py index f057f8cf5..3ec5c984a 100644 --- a/chaco/tools/range_selection.py +++ b/chaco/tools/range_selection.py @@ -19,47 +19,47 @@ class RangeSelection(AbstractController): the user left-clicks to deselect. """ - # The axis to which this tool is perpendicular. + #: The axis to which this tool is perpendicular. axis = Enum("index", "value") - # The selected region, expressed as a tuple in data space. This updates - # and fires change-events as the user is dragging. + #: The selected region, expressed as a tuple in data space. This updates + #: and fires change-events as the user is dragging. selection = Property selection_mode = Enum("set", "append") - # This event is fired whenever the user completes the selection, or when a - # finalized selection gets modified. The value of the event is the data - # space range. + #: This event is fired whenever the user completes the selection, or when a + #: finalized selection gets modified. The value of the event is the data + #: space range. selection_completed = Event - # The name of the metadata on the datasource that we will write - # self.selection to + #: The name of the metadata on the datasource that we will write + #: self.selection to metadata_name = Str("selections") - # Either "set" or "append", depending on whether self.append_key was - # held down + #: Either "set" or "append", depending on whether self.append_key was + #: held down selection_mode_metadata_name = Str("selection_mode") - # The name of the metadata on the datasource that we will set to a numpy - # boolean array for masking the datasource's data + #: The name of the metadata on the datasource that we will set to a numpy + #: boolean array for masking the datasource's data mask_metadata_name = Str("selection_masks") - # The possible event states of this selection tool (overrides - # enable.Interactor). - # - # normal: - # Nothing has been selected, and the user is not dragging the mouse. - # selecting: - # The user is dragging the mouse and actively changing the - # selection region; resizing of an existing selection also - # uses this mode. - # selected: - # The user has released the mouse and a selection has been - # finalized. The selection remains until the user left-clicks - # or self.deselect() is called. - # moving: - # The user moving (not resizing) the selection range. + #: The possible event states of this selection tool (overrides + #: enable.Interactor). + #: + #: normal: + #: Nothing has been selected, and the user is not dragging the mouse. + #: selecting: + #: The user is dragging the mouse and actively changing the + #: selection region; resizing of an existing selection also + #: uses this mode. + #: selected: + #: The user has released the mouse and a selection has been + #: finalized. The selection remains until the user left-clicks + #: or self.deselect() is called. + #: moving: + #: The user moving (not resizing) the selection range. event_state = Enum("normal", "selecting", "selected", "moving") #------------------------------------------------------------------------ @@ -72,48 +72,48 @@ class RangeSelection(AbstractController): # behavior, assign "None" to them. #------------------------------------------------------------------------ - # The plot associated with this tool By default, this is just - # self.component. + #: The plot associated with this tool By default, this is just + #: self.component. plot = Property - # The mapper for associated with this tool. By default, this is the mapper - # on **plot** that corresponds to **axis**. + #: The mapper for associated with this tool. By default, this is the mapper + #: on **plot** that corresponds to **axis**. mapper = Property - # The index to use for **axis**. By default, this is self.plot.orientation, - # but it can be overriden and set to 0 or 1. + #: The index to use for **axis**. By default, this is self.plot.orientation, + #: but it can be overriden and set to 0 or 1. axis_index = Property - # List of listeners that listen to selection events. + #: List of listeners that listen to selection events. listeners = List #------------------------------------------------------------------------ # Configuring interaction control #------------------------------------------------------------------------ - # Can the user resize the selection once it has been drawn? + #: Can the user resize the selection once it has been drawn? enable_resize = Bool(True) - # The pixel distance between the mouse event and a selection endpoint at - # which the user action will be construed as a resize operation. + #: The pixel distance between the mouse event and a selection endpoint at + #: which the user action will be construed as a resize operation. resize_margin = Int(7) - # Allow the left button begin a selection? + #: Allow the left button begin a selection? left_button_selects = Bool(False) - # Disable all left-mouse button interactions? + #: Disable all left-mouse button interactions? disable_left_mouse = Bool(False) - # Allow the tool to be put into the deselected state via mouse clicks + #: Allow the tool to be put into the deselected state via mouse clicks allow_deselection = Bool(True) - # The minimum span, in pixels, of a selection region. Any attempt to - # select a region smaller than this will be treated as a deselection. + #: The minimum span, in pixels, of a selection region. Any attempt to + #: select a region smaller than this will be treated as a deselection. minimum_selection = Int(5) - # The key which, if held down while the mouse is being dragged, will - # indicate that the selection should be appended to an existing selection - # as opposed to overwriting it. + #: The key which, if held down while the mouse is being dragged, will + #: indicate that the selection should be appended to an existing selection + #: as opposed to overwriting it. append_key = Instance(KeySpec, args=(None, "control")) #------------------------------------------------------------------------ diff --git a/chaco/tools/range_selection_overlay.py b/chaco/tools/range_selection_overlay.py index c1e88b6e5..6eb1877a6 100644 --- a/chaco/tools/range_selection_overlay.py +++ b/chaco/tools/range_selection_overlay.py @@ -19,40 +19,40 @@ class RangeSelectionOverlay(AbstractOverlay): selected. """ - # The axis to which this tool is perpendicular. + #: The axis to which this tool is perpendicular. axis = Enum("index", "value") - # Mapping from screen space to data space. By default, it is just - # self.component. + #: Mapping from screen space to data space. By default, it is just + #: self.component. plot = Property(depends_on='component') - # The mapper (and associated range) that drive this RangeSelectionOverlay. - # By default, this is the mapper on self.plot that corresponds to self.axis. + #: The mapper (and associated range) that drive this RangeSelectionOverlay. + #: By default, this is the mapper on self.plot that corresponds to self.axis. mapper = Instance(AbstractMapper) - # The element of an (x,y) tuple that corresponds to the axis index. - # By default, this is set based on self.asix and self.plot.orientation, - # but it can be overriden and set to 0 or 1. + #: The element of an (x,y) tuple that corresponds to the axis index. + #: By default, this is set based on self.asix and self.plot.orientation, + #: but it can be overriden and set to 0 or 1. axis_index = Property - # The name of the metadata to look at for dataspace bounds. The metadata - # can be either a tuple (dataspace_start, dataspace_end) in "selections" or - # a boolean array mask of seleted dataspace points with any other name + #: The name of the metadata to look at for dataspace bounds. The metadata + #: can be either a tuple (dataspace_start, dataspace_end) in "selections" or + #: a boolean array mask of seleted dataspace points with any other name metadata_name = Str("selections") #------------------------------------------------------------------------ # Appearance traits #------------------------------------------------------------------------ - # The color of the selection border line. + #: The color of the selection border line. border_color = ColorTrait("dodgerblue") - # The width, in pixels, of the selection border line. + #: The width, in pixels, of the selection border line. border_width = Float(1.0) - # The line style of the selection border line. + #: The line style of the selection border line. border_style = LineStyle("solid") - # The color to fill the selection region. + #: The color to fill the selection region. fill_color = ColorTrait("lightskyblue") - # The transparency of the fill color. + #: The transparency of the fill color. alpha = Float(0.3) #------------------------------------------------------------------------ diff --git a/chaco/tools/regression_lasso.py b/chaco/tools/regression_lasso.py index 20a71fba3..12f59aff0 100644 --- a/chaco/tools/regression_lasso.py +++ b/chaco/tools/regression_lasso.py @@ -18,13 +18,13 @@ class RegressionLasso(LassoSelection): """ A controller for "lassoing" a selection of points in a regression plot. """ - # The regression updates as more points are added (overrides LassoSelection). + #: The regression updates as more points are added (overrides LassoSelection). incremental_select = True - # Tuple (slope, intercept) of the line that fits the data. + #: Tuple (slope, intercept) of the line that fits the data. fit_params = Any - # The center point of the selected points, in data space. + #: The center point of the selected points, in data space. centroid = Any def _selection_changed_fired(self, event): diff --git a/chaco/tools/save_tool.py b/chaco/tools/save_tool.py index 70aec390b..2ec8a99b0 100755 --- a/chaco/tools/save_tool.py +++ b/chaco/tools/save_tool.py @@ -14,14 +14,14 @@ class SaveTool(BaseTool): the plot component. """ - # The file that the image is saved in. The format will be deduced from - # the extension. + #: The file that the image is saved in. The format will be deduced from + #: the extension. filename = Str("saved_plot.png") - #------------------------------------------------------------------------- - # PDF format options - # This mirror the traits in PdfPlotGraphicsContext. - #------------------------------------------------------------------------- + #:------------------------------------------------------------------------- + #: PDF format options + #: This mirror the traits in PdfPlotGraphicsContext. + #:------------------------------------------------------------------------- pagesize = Enum("letter", "A4") dest_box = Tuple((0.5, 0.5, -0.5, -0.5)) @@ -31,10 +31,10 @@ class SaveTool(BaseTool): # Override default trait values inherited from BaseTool #------------------------------------------------------------------------- - # This tool does not have a visual representation (overrides BaseTool). + #: This tool does not have a visual representation (overrides BaseTool). draw_mode = "none" - # This tool is not visible (overrides BaseTool). + #: This tool is not visible (overrides BaseTool). visible = False def normal_key_pressed(self, event): diff --git a/chaco/tools/scatter_inspector.py b/chaco/tools/scatter_inspector.py index cbb227ca0..77b73a9cf 100644 --- a/chaco/tools/scatter_inspector.py +++ b/chaco/tools/scatter_inspector.py @@ -33,26 +33,26 @@ class ScatterInspector(SelectTool): "hover" key in metadata, and the index of a clicked point to "selection". """ - # If persistent_hover is False, then a point will be de-hovered as soon as - # the mouse leaves its hit-testing area. If persistent_hover is True, then - # a point does no de-hover until another point get hover focus. + #: If persistent_hover is False, then a point will be de-hovered as soon as + #: the mouse leaves its hit-testing area. If persistent_hover is True, then + #: a point does no de-hover until another point get hover focus. persistent_hover = Bool(False) - # The names of the data source metadata for hover and selection events. + #: The names of the data source metadata for hover and selection events. hover_metadata_name = Str('hover') selection_metadata_name = Str('selections') - # This tool emits events when hover or selection changes + #: This tool emits events when hover or selection changes inspector_event = Event(ScatterInspectorEvent) # ------------------------------------------------------------------------- # Override/configure inherited traits # ------------------------------------------------------------------------- - # This tool is not visible + #: This tool is not visible visible = False - # This tool does not have a visual representation + #: This tool does not have a visual representation draw_mode = "none" def normal_mouse_move(self, event): diff --git a/chaco/tools/select_tool.py b/chaco/tools/select_tool.py index f992494d4..4abb9bb1f 100644 --- a/chaco/tools/select_tool.py +++ b/chaco/tools/select_tool.py @@ -12,29 +12,29 @@ class SelectTool(BaseTool): to handle actual selection/deselection. """ - # The threshold, in pixels, around the cursor location to search for points. + #: The threshold, in pixels, around the cursor location to search for points. threshold = Float(5.0) - # How selections are handled: - # - # "toggle" - # The user clicks on points (while optionally holding down a modifier - # key) to select or deselect them. If the point is already selected, - # clicking it again deselects it. The modifier key to use is set by - # **multiselect_modifier**. The only way to deselect points is by - # clicking on them; clicking on a screen space outside of the plot does - # not deselect points. - # "multi" - # Like **toggle** mode, except that the user can deselect all points - # at once by clicking on the plot area away from a point. - # "single" - # The user can only select a single point at a time. - # "off" - # The user cannot select points via clicking. + #: How selections are handled: + #: + #: "toggle" + #: The user clicks on points (while optionally holding down a modifier + #: key) to select or deselect them. If the point is already selected, + #: clicking it again deselects it. The modifier key to use is set by + #: **multiselect_modifier**. The only way to deselect points is by + #: clicking on them; clicking on a screen space outside of the plot does + #: not deselect points. + #: "multi" + #: Like **toggle** mode, except that the user can deselect all points + #: at once by clicking on the plot area away from a point. + #: "single" + #: The user can only select a single point at a time. + #: "off" + #: The user cannot select points via clicking. selection_mode = Enum("toggle", "multi", "single", "off") - # The modifier key to use to multi-select points. Only used in **toggle** - # and **multi** selection modes. + #: The modifier key to use to multi-select points. Only used in **toggle** + #: and **multi** selection modes. multiselect_modifier = Instance(KeySpec, args=(None, "control"), allow_none=True) diff --git a/chaco/tools/simple_inspector.py b/chaco/tools/simple_inspector.py index fbb8a1ffa..b7deddf56 100644 --- a/chaco/tools/simple_inspector.py +++ b/chaco/tools/simple_inspector.py @@ -29,22 +29,22 @@ class SimpleInspectorTool(BaseTool): effect. """ - # This event fires whenever the mouse moves over a new image point. - # Its value is a dict with default keys "x", "y", "index" and "value". + #: This event fires whenever the mouse moves over a new image point. + #: Its value is a dict with default keys "x", "y", "index" and "value". new_value = Event - # Indicates whether overlays listening to this tool should be visible. + #: Indicates whether overlays listening to this tool should be visible. visible = Bool(True) - # Stores the last mouse position. This can be used by overlays to - # position themselves around the mouse. + #: Stores the last mouse position. This can be used by overlays to + #: position themselves around the mouse. last_mouse_position = Tuple - # This key will show and hide any overlays listening to this tool. + #: This key will show and hide any overlays listening to this tool. inspector_key = KeySpec('p') - # A callable that computes other values for the new_value event - # this takes a dictionary as an argument, and returns a dictionary + #: A callable that computes other values for the new_value event + #: this takes a dictionary as an argument, and returns a dictionary value_generator = Callable # Private Trails ######################################################## diff --git a/chaco/tools/traits_tool.py b/chaco/tools/traits_tool.py index e4ce6ec3a..8d84d70d1 100755 --- a/chaco/tools/traits_tool.py +++ b/chaco/tools/traits_tool.py @@ -66,18 +66,18 @@ class TraitsTool(BaseTool): """ Tool to edit the traits of plots, grids, and axes. """ - # This tool does not have a visual representation (overrides BaseTool). + #: This tool does not have a visual representation (overrides BaseTool). draw_mode = "none" - # This tool is not visible (overrides BaseTool). + #: This tool is not visible (overrides BaseTool). visible = False - # The classes of components that should trigger a traits view + #: The classes of components that should trigger a traits view classes = List([PlotAxis, ColorBar]) - # A dict of Class : View providing alternate views for a particular component + #: A dict of Class : View providing alternate views for a particular component views = Dict - # The event to trigger the edit on + #: The event to trigger the edit on event = Str('left_dclick') def _dispatch_stateful_event(self, event, suffix): diff --git a/chaco/tooltip.py b/chaco/tooltip.py index b93e3c569..f517d0acc 100644 --- a/chaco/tooltip.py +++ b/chaco/tooltip.py @@ -21,37 +21,37 @@ class ToolTip(AbstractOverlay): """ An overlay that is a toolip. """ - # The font to render the tooltip. + #: The font to render the tooltip. font = KivaFont('modern 10') - # The color of the text in the tooltip + #: The color of the text in the tooltip text_color = black_color_trait - # The ammount of space between the border and the text. + #: The ammount of space between the border and the text. border_padding = Int(4) - # The number of pixels between lines. + #: The number of pixels between lines. line_spacing = Int(4) - # List of text strings to put in the tooltip. + #: List of text strings to put in the tooltip. lines = List - # Angle to rotate (counterclockwise) in degrees. NB this will *only* - # currently affect text, so probably only useful if borders and background - # are disabled + #: Angle to rotate (counterclockwise) in degrees. NB this will *only* + #: currently affect text, so probably only useful if borders and background + #: are disabled rotate_angle = Float(0.0) - # Should the tooltip automatically reposition itself to remain visible - # and unclipped on its overlaid component? + #: Should the tooltip automatically reposition itself to remain visible + #: and unclipped on its overlaid component? auto_adjust = Bool(True) - # The tooltip is a fixed size. (Overrides PlotComponent.) + #: The tooltip is a fixed size. (Overrides PlotComponent.) resizable = "" - # Use a visible border. (Overrides Enable Component.) + #: Use a visible border. (Overrides Enable Component.) border_visible = True - # Use a white background color (overrides AbstractOverlay). + #: Use a white background color (overrides AbstractOverlay). bgcolor = white_color_trait #---------------------------------------------------------------------- diff --git a/docs/source/conf.py b/docs/source/conf.py index 3b1dcb1de..b1584e0cc 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -24,17 +24,12 @@ def get_build_docset(): BUILD_DOCSET = get_build_docset() -# If your extensions are in another directory, add it here. If the directory -# is relative to the documentation root, use os.path.abspath to make it -# absolute, like shown here. -sys.path.append(os.path.abspath('sphinxext')) - # General configuration # --------------------- # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.autodoc', 'traitsdoc'] +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'traits.util.trait_documenter'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -47,7 +42,7 @@ def get_build_docset(): # General substitutions. project = 'chaco' -copyright = '2008-2017, Enthought, Inc.' +copyright = '2008-2019, Enthought, Inc.' # The default replacements for |version| and |release|, also used in various # other places throughout the built documents. diff --git a/docs/source/sphinxext/LICENSE.txt b/docs/source/sphinxext/LICENSE.txt deleted file mode 100644 index e04d47ea4..000000000 --- a/docs/source/sphinxext/LICENSE.txt +++ /dev/null @@ -1,28 +0,0 @@ -The files docscrape.py, docscrape_sphinx.py and numpydoc.py come from the numpy -Reference Guide project and have the following license. - - -Copyright (C) 2008 Stefan van der Walt , Pauli Virtanen - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met: - - 1. Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - 2. Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in - the documentation and/or other materials provided with the - distribution. - -THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR -IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED -WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, -INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES -(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR -SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, -STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING -IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE -POSSIBILITY OF SUCH DAMAGE. diff --git a/docs/source/sphinxext/comment_eater.py b/docs/source/sphinxext/comment_eater.py deleted file mode 100644 index cb408cd97..000000000 --- a/docs/source/sphinxext/comment_eater.py +++ /dev/null @@ -1,167 +0,0 @@ -from cStringIO import StringIO -import compiler -import inspect -import textwrap -import tokenize - -from compiler_unparse import unparse - - -class Comment(object): - """ A comment block. - """ - is_comment = True - def __init__(self, start_lineno, end_lineno, text): - # int : The first line number in the block. 1-indexed. - self.start_lineno = start_lineno - # int : The last line number. Inclusive! - self.end_lineno = end_lineno - # str : The text block including '#' character but not any leading spaces. - self.text = text - # int: NL sentinel to check how many continues newlines we have - # encountered. - self.NLs = 0 - - def add(self, string, start, end, line): - """ Add a new comment line. - """ - self.start_lineno = min(self.start_lineno, start[0]) - self.end_lineno = max(self.end_lineno, end[0]) - self.text += string - - if string == '\n': - self.NLs += 1 - else: - self.NLs = 0 - - def __repr__(self): - return '%s(%r, %r, %r)' % (self.__class__.__name__, self.start_lineno, - self.end_lineno, self.text) - - -class NonComment(object): - """ A non-comment block of code. - """ - is_comment = False - def __init__(self, start_lineno, end_lineno): - self.start_lineno = start_lineno - self.end_lineno = end_lineno - - def add(self, string, start, end, line): - """ Add lines to the block. - """ - if string.strip(): - # Only add if not entirely whitespace. - self.start_lineno = min(self.start_lineno, start[0]) - self.end_lineno = max(self.end_lineno, end[0]) - - def __repr__(self): - return '%s(%r, %r)' % (self.__class__.__name__, self.start_lineno, - self.end_lineno) - - -class CommentBlocker(object): - """ Pull out contiguous comment blocks. - """ - def __init__(self): - # Start with a dummy. - self.current_block = NonComment(0, 0) - - # All of the blocks seen so far. - self.blocks = [] - - # The index mapping lines of code to their associated comment blocks. - self.index = {} - - def process_file(self, file): - """ Process a file object. - """ - for token in tokenize.generate_tokens(file.next): - self.process_token(*token) - self.make_index() - - def process_token(self, kind, string, start, end, line): - """ Process a single token. - """ - block = self.current_block - if (block.is_comment) and block.NLs < 2 : - if kind in (tokenize.COMMENT, tokenize.NL): - block.add(string, start, end, line) - else: - self.new_noncomment(start[0], end[0]) - else: - if kind == tokenize.COMMENT: - self.new_comment(string, start, end, line) - else: - block.add(string, start, end, line) - - def new_noncomment(self, start_lineno, end_lineno): - """ We are transitioning from a noncomment to a comment. - """ - block = NonComment(start_lineno, end_lineno) - self.blocks.append(block) - self.current_block = block - - def new_comment(self, string, start, end, line): - """ Possibly add a new comment. - - Only adds a new comment if this comment is the only thing on the line. - Otherwise, it extends the noncomment block. - """ - prefix = line[:start[1]] - if prefix.strip(): - # Oops! Trailing comment, not a comment block. - self.current_block.add(string, start, end, line) - else: - # A comment block. - block = Comment(start[0], end[0], string) - self.blocks.append(block) - self.current_block = block - - def make_index(self): - """ Make the index mapping lines of actual code to their associated - prefix comments. - """ - for prev, block in zip(self.blocks[:-1], self.blocks[1:]): - if not block.is_comment: - self.index[block.start_lineno] = prev - - def search_for_comment(self, lineno, default=None): - """ Find the comment block just before the given line number. - - Returns None (or the specified default) if there is no such block. - """ - if not self.index: - self.make_index() - block = self.index.get(lineno, None) - text = getattr(block, 'text', default) - return text - - -def strip_comment_marker(text): - """ Strip # markers at the front of a block of comment text. - """ - lines = [] - for line in text.splitlines(): - lines.append(line.lstrip('#')) - text = textwrap.dedent('\n'.join(lines)) - return text - - -def get_class_traits(klass): - """ Yield all of the documentation for trait definitions on a class object. - """ - # FIXME: gracefully handle errors here or in the caller? - source = inspect.getsource(klass) - cb = CommentBlocker() - cb.process_file(StringIO(source)) - mod_ast = compiler.parse(source) - class_ast = mod_ast.node.nodes[0] - for node in class_ast.code.nodes: - # FIXME: handle other kinds of assignments? - if isinstance(node, compiler.ast.Assign): - name = node.nodes[0].name - rhs = unparse(node.expr).strip() - doc = strip_comment_marker(cb.search_for_comment(node.lineno, default='')) - yield name, rhs, doc - diff --git a/docs/source/sphinxext/compiler_unparse.py b/docs/source/sphinxext/compiler_unparse.py deleted file mode 100644 index d62d65c2e..000000000 --- a/docs/source/sphinxext/compiler_unparse.py +++ /dev/null @@ -1,860 +0,0 @@ -""" Turn compiler.ast structures back into executable python code. - - The unparse method takes a compiler.ast tree and transforms it back into - valid python code. It is incomplete and currently only works for - import statements, function calls, function definitions, assignments, and - basic expressions. - - Inspired by python-2.5-svn/Demo/parser/unparse.py - - fixme: We may want to move to using _ast trees because the compiler for - them is about 6 times faster than compiler.compile. -""" - -import sys -import cStringIO -from compiler.ast import Const, Name, Tuple, Div, Mul, Sub, Add - -def unparse(ast, single_line_functions=False): - s = cStringIO.StringIO() - UnparseCompilerAst(ast, s, single_line_functions) - return s.getvalue().lstrip() - -op_precedence = { 'compiler.ast.Power':3, 'compiler.ast.Mul':2, 'compiler.ast.Div':2, - 'compiler.ast.Add':1, 'compiler.ast.Sub':1 } - -class UnparseCompilerAst: - """ Methods in this class recursively traverse an AST and - output source code for the abstract syntax; original formatting - is disregarged. - """ - - ######################################################################### - # object interface. - ######################################################################### - - def __init__(self, tree, file = sys.stdout, single_line_functions=False): - """ Unparser(tree, file=sys.stdout) -> None. - - Print the source for tree to file. - """ - self.f = file - self._single_func = single_line_functions - self._do_indent = True - self._indent = 0 - self._dispatch(tree) - self._write("\n") - self.f.flush() - - ######################################################################### - # Unparser private interface. - ######################################################################### - - ### format, output, and dispatch methods ################################ - - def _fill(self, text = ""): - "Indent a piece of text, according to the current indentation level" - if self._do_indent: - self._write("\n"+" "*self._indent + text) - else: - self._write(text) - - def _write(self, text): - "Append a piece of text to the current line." - self.f.write(text) - - def _enter(self): - "Print ':', and increase the indentation." - self._write(": ") - self._indent += 1 - - def _leave(self): - "Decrease the indentation level." - self._indent -= 1 - - def _dispatch(self, tree): - "_dispatcher function, _dispatching tree type T to method _T." - if isinstance(tree, list): - for t in tree: - self._dispatch(t) - return - meth = getattr(self, "_"+tree.__class__.__name__) - if tree.__class__.__name__ == 'NoneType' and not self._do_indent: - return - meth(tree) - - - ######################################################################### - # compiler.ast unparsing methods. - # - # There should be one method per concrete grammar type. They are - # organized in alphabetical order. - ######################################################################### - - def _Add(self, t): - self.__binary_op(t, '+') - - def _And(self, t): - self._write(" (") - for i, node in enumerate(t.nodes): - self._dispatch(node) - if i != len(t.nodes)-1: - self._write(") and (") - self._write(")") - - def _AssAttr(self, t): - """ Handle assigning an attribute of an object - """ - self._dispatch(t.expr) - self._write('.'+t.attrname) - - def _Assign(self, t): - """ Expression Assignment such as "a = 1". - - This only handles assignment in expressions. Keyword assignment - is handled separately. - """ - self._fill() - for target in t.nodes: - self._dispatch(target) - self._write(" = ") - self._dispatch(t.expr) - if not self._do_indent: - self._write('; ') - - def _AssName(self, t): - """ Name on left hand side of expression. - - Treat just like a name on the right side of an expression. - """ - self._Name(t) - - def _AssTuple(self, t): - """ Tuple on left hand side of an expression. - """ - - # _write each elements, separated by a comma. - for element in t.nodes[:-1]: - self._dispatch(element) - self._write(", ") - - # Handle the last one without writing comma - last_element = t.nodes[-1] - self._dispatch(last_element) - - def _AugAssign(self, t): - """ +=,-=,*=,/=,**=, etc. operations - """ - - self._fill() - self._dispatch(t.node) - self._write(' '+t.op+' ') - self._dispatch(t.expr) - if not self._do_indent: - self._write(';') - - def _Bitand(self, t): - """ Bit and operation. - """ - - for i, node in enumerate(t.nodes): - self._write("(") - self._dispatch(node) - self._write(")") - if i != len(t.nodes)-1: - self._write(" & ") - - def _Bitor(self, t): - """ Bit or operation - """ - - for i, node in enumerate(t.nodes): - self._write("(") - self._dispatch(node) - self._write(")") - if i != len(t.nodes)-1: - self._write(" | ") - - def _CallFunc(self, t): - """ Function call. - """ - self._dispatch(t.node) - self._write("(") - comma = False - for e in t.args: - if comma: self._write(", ") - else: comma = True - self._dispatch(e) - if t.star_args: - if comma: self._write(", ") - else: comma = True - self._write("*") - self._dispatch(t.star_args) - if t.dstar_args: - if comma: self._write(", ") - else: comma = True - self._write("**") - self._dispatch(t.dstar_args) - self._write(")") - - def _Compare(self, t): - self._dispatch(t.expr) - for op, expr in t.ops: - self._write(" " + op + " ") - self._dispatch(expr) - - def _Const(self, t): - """ A constant value such as an integer value, 3, or a string, "hello". - """ - self._dispatch(t.value) - - def _Decorators(self, t): - """ Handle function decorators (eg. @has_units) - """ - for node in t.nodes: - self._dispatch(node) - - def _Dict(self, t): - self._write("{") - for i, (k, v) in enumerate(t.items): - self._dispatch(k) - self._write(": ") - self._dispatch(v) - if i < len(t.items)-1: - self._write(", ") - self._write("}") - - def _Discard(self, t): - """ Node for when return value is ignored such as in "foo(a)". - """ - self._fill() - self._dispatch(t.expr) - - def _Div(self, t): - self.__binary_op(t, '/') - - def _Ellipsis(self, t): - self._write("...") - - def _From(self, t): - """ Handle "from xyz import foo, bar as baz". - """ - # fixme: Are From and ImportFrom handled differently? - self._fill("from ") - self._write(t.modname) - self._write(" import ") - for i, (name,asname) in enumerate(t.names): - if i != 0: - self._write(", ") - self._write(name) - if asname is not None: - self._write(" as "+asname) - - def _Function(self, t): - """ Handle function definitions - """ - if t.decorators is not None: - self._fill("@") - self._dispatch(t.decorators) - self._fill("def "+t.name + "(") - defaults = [None] * (len(t.argnames) - len(t.defaults)) + list(t.defaults) - for i, arg in enumerate(zip(t.argnames, defaults)): - self._write(arg[0]) - if arg[1] is not None: - self._write('=') - self._dispatch(arg[1]) - if i < len(t.argnames)-1: - self._write(', ') - self._write(")") - if self._single_func: - self._do_indent = False - self._enter() - self._dispatch(t.code) - self._leave() - self._do_indent = True - - def _Getattr(self, t): - """ Handle getting an attribute of an object - """ - if isinstance(t.expr, (Div, Mul, Sub, Add)): - self._write('(') - self._dispatch(t.expr) - self._write(')') - else: - self._dispatch(t.expr) - - self._write('.'+t.attrname) - - def _If(self, t): - self._fill() - - for i, (compare,code) in enumerate(t.tests): - if i == 0: - self._write("if ") - else: - self._write("elif ") - self._dispatch(compare) - self._enter() - self._fill() - self._dispatch(code) - self._leave() - self._write("\n") - - if t.else_ is not None: - self._write("else") - self._enter() - self._fill() - self._dispatch(t.else_) - self._leave() - self._write("\n") - - def _IfExp(self, t): - self._dispatch(t.then) - self._write(" if ") - self._dispatch(t.test) - - if t.else_ is not None: - self._write(" else (") - self._dispatch(t.else_) - self._write(")") - - def _Import(self, t): - """ Handle "import xyz.foo". - """ - self._fill("import ") - - for i, (name,asname) in enumerate(t.names): - if i != 0: - self._write(", ") - self._write(name) - if asname is not None: - self._write(" as "+asname) - - def _Keyword(self, t): - """ Keyword value assignment within function calls and definitions. - """ - self._write(t.name) - self._write("=") - self._dispatch(t.expr) - - def _List(self, t): - self._write("[") - for i,node in enumerate(t.nodes): - self._dispatch(node) - if i < len(t.nodes)-1: - self._write(", ") - self._write("]") - - def _Module(self, t): - if t.doc is not None: - self._dispatch(t.doc) - self._dispatch(t.node) - - def _Mul(self, t): - self.__binary_op(t, '*') - - def _Name(self, t): - self._write(t.name) - - def _NoneType(self, t): - self._write("None") - - def _Not(self, t): - self._write('not (') - self._dispatch(t.expr) - self._write(')') - - def _Or(self, t): - self._write(" (") - for i, node in enumerate(t.nodes): - self._dispatch(node) - if i != len(t.nodes)-1: - self._write(") or (") - self._write(")") - - def _Pass(self, t): - self._write("pass\n") - - def _Printnl(self, t): - self._fill("print ") - if t.dest: - self._write(">> ") - self._dispatch(t.dest) - self._write(", ") - comma = False - for node in t.nodes: - if comma: self._write(', ') - else: comma = True - self._dispatch(node) - - def _Power(self, t): - self.__binary_op(t, '**') - - def _Return(self, t): - self._fill("return ") - if t.value: - if isinstance(t.value, Tuple): - text = ', '.join([ name.name for name in t.value.asList() ]) - self._write(text) - else: - self._dispatch(t.value) - if not self._do_indent: - self._write('; ') - - def _Slice(self, t): - self._dispatch(t.expr) - self._write("[") - if t.lower: - self._dispatch(t.lower) - self._write(":") - if t.upper: - self._dispatch(t.upper) - #if t.step: - # self._write(":") - # self._dispatch(t.step) - self._write("]") - - def _Sliceobj(self, t): - for i, node in enumerate(t.nodes): - if i != 0: - self._write(":") - if not (isinstance(node, Const) and node.value is None): - self._dispatch(node) - - def _Stmt(self, tree): - for node in tree.nodes: - self._dispatch(node) - - def _Sub(self, t): - self.__binary_op(t, '-') - - def _Subscript(self, t): - self._dispatch(t.expr) - self._write("[") - for i, value in enumerate(t.subs): - if i != 0: - self._write(",") - self._dispatch(value) - self._write("]") - - def _TryExcept(self, t): - self._fill("try") - self._enter() - self._dispatch(t.body) - self._leave() - - for handler in t.handlers: - self._fill('except ') - self._dispatch(handler[0]) - if handler[1] is not None: - self._write(', ') - self._dispatch(handler[1]) - self._enter() - self._dispatch(handler[2]) - self._leave() - - if t.else_: - self._fill("else") - self._enter() - self._dispatch(t.else_) - self._leave() - - def _Tuple(self, t): - - if not t.nodes: - # Empty tuple. - self._write("()") - else: - self._write("(") - - # _write each elements, separated by a comma. - for element in t.nodes[:-1]: - self._dispatch(element) - self._write(", ") - - # Handle the last one without writing comma - last_element = t.nodes[-1] - self._dispatch(last_element) - - self._write(")") - - def _UnaryAdd(self, t): - self._write("+") - self._dispatch(t.expr) - - def _UnarySub(self, t): - self._write("-") - self._dispatch(t.expr) - - def _With(self, t): - self._fill('with ') - self._dispatch(t.expr) - if t.vars: - self._write(' as ') - self._dispatch(t.vars.name) - self._enter() - self._dispatch(t.body) - self._leave() - self._write('\n') - - def _int(self, t): - self._write(repr(t)) - - def __binary_op(self, t, symbol): - # Check if parenthesis are needed on left side and then dispatch - has_paren = False - left_class = str(t.left.__class__) - if (left_class in op_precedence.keys() and - op_precedence[left_class] < op_precedence[str(t.__class__)]): - has_paren = True - if has_paren: - self._write('(') - self._dispatch(t.left) - if has_paren: - self._write(')') - # Write the appropriate symbol for operator - self._write(symbol) - # Check if parenthesis are needed on the right side and then dispatch - has_paren = False - right_class = str(t.right.__class__) - if (right_class in op_precedence.keys() and - op_precedence[right_class] < op_precedence[str(t.__class__)]): - has_paren = True - if has_paren: - self._write('(') - self._dispatch(t.right) - if has_paren: - self._write(')') - - def _float(self, t): - # if t is 0.1, str(t)->'0.1' while repr(t)->'0.1000000000001' - # We prefer str here. - self._write(str(t)) - - def _str(self, t): - self._write(repr(t)) - - def _tuple(self, t): - self._write(str(t)) - - ######################################################################### - # These are the methods from the _ast modules unparse. - # - # As our needs to handle more advanced code increase, we may want to - # modify some of the methods below so that they work for compiler.ast. - ######################################################################### - -# # stmt -# def _Expr(self, tree): -# self._fill() -# self._dispatch(tree.value) -# -# def _Import(self, t): -# self._fill("import ") -# first = True -# for a in t.names: -# if first: -# first = False -# else: -# self._write(", ") -# self._write(a.name) -# if a.asname: -# self._write(" as "+a.asname) -# -## def _ImportFrom(self, t): -## self._fill("from ") -## self._write(t.module) -## self._write(" import ") -## for i, a in enumerate(t.names): -## if i == 0: -## self._write(", ") -## self._write(a.name) -## if a.asname: -## self._write(" as "+a.asname) -## # XXX(jpe) what is level for? -## -# -# def _Break(self, t): -# self._fill("break") -# -# def _Continue(self, t): -# self._fill("continue") -# -# def _Delete(self, t): -# self._fill("del ") -# self._dispatch(t.targets) -# -# def _Assert(self, t): -# self._fill("assert ") -# self._dispatch(t.test) -# if t.msg: -# self._write(", ") -# self._dispatch(t.msg) -# -# def _Exec(self, t): -# self._fill("exec ") -# self._dispatch(t.body) -# if t.globals: -# self._write(" in ") -# self._dispatch(t.globals) -# if t.locals: -# self._write(", ") -# self._dispatch(t.locals) -# -# def _Print(self, t): -# self._fill("print ") -# do_comma = False -# if t.dest: -# self._write(">>") -# self._dispatch(t.dest) -# do_comma = True -# for e in t.values: -# if do_comma:self._write(", ") -# else:do_comma=True -# self._dispatch(e) -# if not t.nl: -# self._write(",") -# -# def _Global(self, t): -# self._fill("global") -# for i, n in enumerate(t.names): -# if i != 0: -# self._write(",") -# self._write(" " + n) -# -# def _Yield(self, t): -# self._fill("yield") -# if t.value: -# self._write(" (") -# self._dispatch(t.value) -# self._write(")") -# -# def _Raise(self, t): -# self._fill('raise ') -# if t.type: -# self._dispatch(t.type) -# if t.inst: -# self._write(", ") -# self._dispatch(t.inst) -# if t.tback: -# self._write(", ") -# self._dispatch(t.tback) -# -# -# def _TryFinally(self, t): -# self._fill("try") -# self._enter() -# self._dispatch(t.body) -# self._leave() -# -# self._fill("finally") -# self._enter() -# self._dispatch(t.finalbody) -# self._leave() -# -# def _excepthandler(self, t): -# self._fill("except ") -# if t.type: -# self._dispatch(t.type) -# if t.name: -# self._write(", ") -# self._dispatch(t.name) -# self._enter() -# self._dispatch(t.body) -# self._leave() -# -# def _ClassDef(self, t): -# self._write("\n") -# self._fill("class "+t.name) -# if t.bases: -# self._write("(") -# for a in t.bases: -# self._dispatch(a) -# self._write(", ") -# self._write(")") -# self._enter() -# self._dispatch(t.body) -# self._leave() -# -# def _FunctionDef(self, t): -# self._write("\n") -# for deco in t.decorators: -# self._fill("@") -# self._dispatch(deco) -# self._fill("def "+t.name + "(") -# self._dispatch(t.args) -# self._write(")") -# self._enter() -# self._dispatch(t.body) -# self._leave() -# -# def _For(self, t): -# self._fill("for ") -# self._dispatch(t.target) -# self._write(" in ") -# self._dispatch(t.iter) -# self._enter() -# self._dispatch(t.body) -# self._leave() -# if t.orelse: -# self._fill("else") -# self._enter() -# self._dispatch(t.orelse) -# self._leave -# -# def _While(self, t): -# self._fill("while ") -# self._dispatch(t.test) -# self._enter() -# self._dispatch(t.body) -# self._leave() -# if t.orelse: -# self._fill("else") -# self._enter() -# self._dispatch(t.orelse) -# self._leave -# -# # expr -# def _Str(self, tree): -# self._write(repr(tree.s)) -## -# def _Repr(self, t): -# self._write("`") -# self._dispatch(t.value) -# self._write("`") -# -# def _Num(self, t): -# self._write(repr(t.n)) -# -# def _ListComp(self, t): -# self._write("[") -# self._dispatch(t.elt) -# for gen in t.generators: -# self._dispatch(gen) -# self._write("]") -# -# def _GeneratorExp(self, t): -# self._write("(") -# self._dispatch(t.elt) -# for gen in t.generators: -# self._dispatch(gen) -# self._write(")") -# -# def _comprehension(self, t): -# self._write(" for ") -# self._dispatch(t.target) -# self._write(" in ") -# self._dispatch(t.iter) -# for if_clause in t.ifs: -# self._write(" if ") -# self._dispatch(if_clause) -# -# def _IfExp(self, t): -# self._dispatch(t.body) -# self._write(" if ") -# self._dispatch(t.test) -# if t.orelse: -# self._write(" else ") -# self._dispatch(t.orelse) -# -# unop = {"Invert":"~", "Not": "not", "UAdd":"+", "USub":"-"} -# def _UnaryOp(self, t): -# self._write(self.unop[t.op.__class__.__name__]) -# self._write("(") -# self._dispatch(t.operand) -# self._write(")") -# -# binop = { "Add":"+", "Sub":"-", "Mult":"*", "Div":"/", "Mod":"%", -# "LShift":">>", "RShift":"<<", "BitOr":"|", "BitXor":"^", "BitAnd":"&", -# "FloorDiv":"//", "Pow": "**"} -# def _BinOp(self, t): -# self._write("(") -# self._dispatch(t.left) -# self._write(")" + self.binop[t.op.__class__.__name__] + "(") -# self._dispatch(t.right) -# self._write(")") -# -# boolops = {_ast.And: 'and', _ast.Or: 'or'} -# def _BoolOp(self, t): -# self._write("(") -# self._dispatch(t.values[0]) -# for v in t.values[1:]: -# self._write(" %s " % self.boolops[t.op.__class__]) -# self._dispatch(v) -# self._write(")") -# -# def _Attribute(self,t): -# self._dispatch(t.value) -# self._write(".") -# self._write(t.attr) -# -## def _Call(self, t): -## self._dispatch(t.func) -## self._write("(") -## comma = False -## for e in t.args: -## if comma: self._write(", ") -## else: comma = True -## self._dispatch(e) -## for e in t.keywords: -## if comma: self._write(", ") -## else: comma = True -## self._dispatch(e) -## if t.starargs: -## if comma: self._write(", ") -## else: comma = True -## self._write("*") -## self._dispatch(t.starargs) -## if t.kwargs: -## if comma: self._write(", ") -## else: comma = True -## self._write("**") -## self._dispatch(t.kwargs) -## self._write(")") -# -# # slice -# def _Index(self, t): -# self._dispatch(t.value) -# -# def _ExtSlice(self, t): -# for i, d in enumerate(t.dims): -# if i != 0: -# self._write(': ') -# self._dispatch(d) -# -# # others -# def _arguments(self, t): -# first = True -# nonDef = len(t.args)-len(t.defaults) -# for a in t.args[0:nonDef]: -# if first:first = False -# else: self._write(", ") -# self._dispatch(a) -# for a,d in zip(t.args[nonDef:], t.defaults): -# if first:first = False -# else: self._write(", ") -# self._dispatch(a), -# self._write("=") -# self._dispatch(d) -# if t.vararg: -# if first:first = False -# else: self._write(", ") -# self._write("*"+t.vararg) -# if t.kwarg: -# if first:first = False -# else: self._write(", ") -# self._write("**"+t.kwarg) -# -## def _keyword(self, t): -## self._write(t.arg) -## self._write("=") -## self._dispatch(t.value) -# -# def _Lambda(self, t): -# self._write("lambda ") -# self._dispatch(t.args) -# self._write(": ") -# self._dispatch(t.body) - - - diff --git a/docs/source/sphinxext/docscrape.py b/docs/source/sphinxext/docscrape.py deleted file mode 100644 index 5e808e51d..000000000 --- a/docs/source/sphinxext/docscrape.py +++ /dev/null @@ -1,480 +0,0 @@ -"""Extract reference documentation from the NumPy source tree. - -""" - -import inspect -import textwrap -import re -import pydoc -from StringIO import StringIO -from warnings import warn - -class Reader(object): - """A line-based string reader. - - """ - def __init__(self, data): - """ - Parameters - ---------- - data : str - String with lines separated by '\n'. - - """ - if isinstance(data,list): - self._str = data - else: - self._str = data.split('\n') # store string as list of lines - - self.reset() - - def __getitem__(self, n): - return self._str[n] - - def reset(self): - self._l = 0 # current line nr - - def read(self): - if not self.eof(): - out = self[self._l] - self._l += 1 - return out - else: - return '' - - def seek_next_non_empty_line(self): - for l in self[self._l:]: - if l.strip(): - break - else: - self._l += 1 - - def eof(self): - return self._l >= len(self._str) - - def read_to_condition(self, condition_func): - start = self._l - for line in self[start:]: - if condition_func(line): - return self[start:self._l] - self._l += 1 - if self.eof(): - return self[start:self._l+1] - return [] - - def read_to_next_empty_line(self): - self.seek_next_non_empty_line() - def is_empty(line): - return not line.strip() - return self.read_to_condition(is_empty) - - def read_to_next_unindented_line(self): - def is_unindented(line): - return (line.strip() and (len(line.lstrip()) == len(line))) - return self.read_to_condition(is_unindented) - - def peek(self,n=0): - if self._l + n < len(self._str): - return self[self._l + n] - else: - return '' - - def is_empty(self): - return not ''.join(self._str).strip() - - -class NumpyDocString(object): - def __init__(self,docstring): - docstring = docstring.split('\n') - - # De-indent paragraph - try: - indent = min(len(s) - len(s.lstrip()) for s in docstring - if s.strip()) - except ValueError: - indent = 0 - - for n,line in enumerate(docstring): - docstring[n] = docstring[n][indent:] - - self._doc = Reader(docstring) - self._parsed_data = { - 'Signature': '', - 'Summary': '', - 'Extended Summary': [], - 'Parameters': [], - 'Returns': [], - 'Raises': [], - 'Warns': [], - 'Other Parameters': [], - 'Attributes': [], - 'Methods': [], - 'See Also': [], - 'Notes': [], - 'References': '', - 'Examples': '', - 'index': {} - } - - self._parse() - - def __getitem__(self,key): - return self._parsed_data[key] - - def __setitem__(self,key,val): - if not self._parsed_data.has_key(key): - warn("Unknown section %s" % key) - else: - self._parsed_data[key] = val - - def _is_at_section(self): - self._doc.seek_next_non_empty_line() - - if self._doc.eof(): - return False - - l1 = self._doc.peek().strip() # e.g. Parameters - - if l1.startswith('.. index::'): - return True - - l2 = self._doc.peek(1).strip() # ---------- - return l2.startswith('-'*len(l1)) - - def _strip(self,doc): - i = 0 - j = 0 - for i,line in enumerate(doc): - if line.strip(): break - - for j,line in enumerate(doc[::-1]): - if line.strip(): break - - return doc[i:len(doc)-j] - - def _read_to_next_section(self): - section = self._doc.read_to_next_empty_line() - - while not self._is_at_section() and not self._doc.eof(): - if not self._doc.peek(-1).strip(): # previous line was empty - section += [''] - - section += self._doc.read_to_next_empty_line() - - return section - - def _read_sections(self): - while not self._doc.eof(): - data = self._read_to_next_section() - name = data[0].strip() - - if name.startswith('..'): # index section - yield name, data[1:] - elif len(data) < 2: - yield StopIteration - else: - yield name, self._strip(data[2:]) - - def _parse_param_list(self,content): - r = Reader(content) - params = [] - while not r.eof(): - header = r.read().strip() - if ' : ' in header: - arg_name, arg_type = header.split(' : ')[:2] - else: - arg_name, arg_type = header, '' - - desc = r.read_to_next_unindented_line() - for n,line in enumerate(desc): - desc[n] = line.strip() - desc = desc #'\n'.join(desc) - - params.append((arg_name,arg_type,desc)) - - return params - - def _parse_see_also(self, content): - """ - func_name : Descriptive text - continued text - another_func_name : Descriptive text - func_name1, func_name2, func_name3 - - """ - functions = [] - current_func = None - rest = [] - for line in content: - if not line.strip(): continue - if ':' in line: - if current_func: - functions.append((current_func, rest)) - r = line.split(':', 1) - current_func = r[0].strip() - r[1] = r[1].strip() - if r[1]: - rest = [r[1]] - else: - rest = [] - elif not line.startswith(' '): - if current_func: - functions.append((current_func, rest)) - current_func = None - rest = [] - if ',' in line: - for func in line.split(','): - func = func.strip() - if func: - functions.append((func, [])) - elif line.strip(): - current_func = line.strip() - elif current_func is not None: - rest.append(line.strip()) - if current_func: - functions.append((current_func, rest)) - return functions - - def _parse_index(self, section, content): - """ - .. index: default - :refguide: something, else, and more - - """ - def strip_each_in(lst): - return [s.strip() for s in lst] - - out = {} - section = section.split('::') - if len(section) > 1: - out['default'] = strip_each_in(section[1].split(','))[0] - for line in content: - line = line.split(':') - if len(line) > 2: - out[line[1]] = strip_each_in(line[2].split(',')) - return out - - def _parse_summary(self): - """Grab signature (if given) and summary""" - if self._is_at_section(): - return - - summary = self._doc.read_to_next_empty_line() - summary_str = " ".join([s.strip() for s in summary]).strip() - if re.compile('^([\w., ]+=)?\s*[\w\.]+\(.*\)$').match(summary_str): - self['Signature'] = summary_str - if not self._is_at_section(): - self['Summary'] = self._doc.read_to_next_empty_line() - else: - self['Summary'] = summary - - if not self._is_at_section(): - self['Extended Summary'] = self._read_to_next_section() - - def _parse(self): - self._doc.reset() - self._parse_summary() - - for (section,content) in self._read_sections(): - if not section.startswith('..'): - section = ' '.join([s.capitalize() for s in section.split(' ')]) - if section in ('Parameters', 'Attributes', 'Methods', - 'Returns', 'Raises', 'Warns'): - self[section] = self._parse_param_list(content) - elif section.startswith('.. index::'): - self['index'] = self._parse_index(section, content) - elif section == 'See Also': - self['See Also'] = self._parse_see_also(content) - else: - self[section] = content - - # string conversion routines - - def _str_header(self, name, symbol='-'): - return [name, len(name)*symbol] - - def _str_indent(self, doc, indent=4): - out = [] - for line in doc: - out += [' '*indent + line] - return out - - def _str_signature(self): - if self['Signature']: - return [self['Signature'].replace('*','\*')] + [''] - else: - return [''] - - def _str_summary(self): - if self['Summary']: - return self['Summary'] + [''] - else: - return [] - - def _str_extended_summary(self): - if self['Extended Summary']: - return self['Extended Summary'] + [''] - else: - return [] - - def _str_param_list(self, name): - out = [] - if self[name]: - out += self._str_header(name) - for param,param_type,desc in self[name]: - out += ['%s : %s' % (param, param_type)] - out += self._str_indent(desc) - out += [''] - return out - - def _str_section(self, name): - out = [] - if self[name]: - out += self._str_header(name) - out += self[name] - out += [''] - return out - - def _str_see_also(self, func_role): - if not self['See Also']: return [] - out = [] - out += self._str_header("See Also") - last_had_desc = True - for func, desc in self['See Also']: - if func_role: - link = ':%s:`%s`' % (func_role, func) - else: - link = "`%s`_" % func - if desc or last_had_desc: - out += [''] - out += [link] - else: - out[-1] += ", %s" % link - if desc: - out += self._str_indent(desc) - last_had_desc = True - else: - last_had_desc = False - out += [''] - return out - - def _str_index(self): - idx = self['index'] - out = [] - out += ['.. index:: %s' % idx.get('default','')] - for section, references in idx.iteritems(): - if section == 'default': - continue - out += [' :%s: %s' % (section, ', '.join(references))] - return out - - def __str__(self, func_role=''): - out = [] - out += self._str_signature() - out += self._str_summary() - out += self._str_extended_summary() - for param_list in ('Parameters','Returns','Raises'): - out += self._str_param_list(param_list) - out += self._str_see_also(func_role) - for s in ('Notes','References','Examples'): - out += self._str_section(s) - out += self._str_index() - return '\n'.join(out) - - -def indent(str,indent=4): - indent_str = ' '*indent - if str is None: - return indent_str - lines = str.split('\n') - return '\n'.join(indent_str + l for l in lines) - -def header(text, style='-'): - return text + '\n' + style*len(text) + '\n' - - -class FunctionDoc(NumpyDocString): - def __init__(self, func, role='func'): - self._f = func - self._role = role # e.g. "func" or "meth" - try: - NumpyDocString.__init__(self,inspect.getdoc(func) or '') - except ValueError as e: - print '*'*78 - print "ERROR: '%s' while parsing `%s`" % (e, self._f) - print '*'*78 - #print "Docstring follows:" - #print doclines - #print '='*78 - - if not self['Signature']: - func, func_name = self.get_func() - try: - # try to read signature - argspec = inspect.getargspec(func) - argspec = inspect.formatargspec(*argspec) - argspec = argspec.replace('*','\*') - signature = '%s%s' % (func_name, argspec) - except TypeError as e: - signature = '%s()' % func_name - self['Signature'] = signature - - def get_func(self): - func_name = getattr(self._f, '__name__', self.__class__.__name__) - if hasattr(self._f, '__class__') or inspect.isclass(self._f): - func = getattr(self._f, '__call__', self._f.__init__) - else: - func = self._f - return func, func_name - - def __str__(self): - out = '' - - func, func_name = self.get_func() - signature = self['Signature'].replace('*', '\*') - - roles = {'func': 'function', - 'meth': 'method'} - - if self._role: - if self._role not in roles: - print "Warning: invalid role %s" % self._role - out += '.. %s:: %s\n \n\n' % (roles.get(self._role,''), - func_name) - - out += super(FunctionDoc, self).__str__(func_role=self._role) - return out - - -class ClassDoc(NumpyDocString): - def __init__(self,cls,modulename='',func_doc=FunctionDoc): - if not inspect.isclass(cls): - raise ValueError("Initialise using a class. Got %r" % cls) - self._cls = cls - - if modulename and not modulename.endswith('.'): - modulename += '.' - self._mod = modulename - self._name = cls.__name__ - self._func_doc = func_doc - - NumpyDocString.__init__(self, pydoc.getdoc(cls)) - - @property - def methods(self): - return [name for name,func in inspect.getmembers(self._cls) - if not name.startswith('_') and callable(func)] - - def __str__(self): - out = '' - out += super(ClassDoc, self).__str__() - out += "\n\n" - - #for m in self.methods: - # print "Parsing `%s`" % m - # out += str(self._func_doc(getattr(self._cls,m), 'meth')) + '\n\n' - # out += '.. index::\n single: %s; %s\n\n' % (self._name, m) - - return out - - diff --git a/docs/source/sphinxext/docscrape_sphinx.py b/docs/source/sphinxext/docscrape_sphinx.py deleted file mode 100644 index a644866fa..000000000 --- a/docs/source/sphinxext/docscrape_sphinx.py +++ /dev/null @@ -1,108 +0,0 @@ -import re, textwrap -from docscrape import NumpyDocString, FunctionDoc, ClassDoc - -class SphinxDocString(NumpyDocString): - # string conversion routines - def _str_header(self, name, symbol='`'): - return ['.. rubric:: ' + name, ''] - - def _str_field_list(self, name): - return [':' + name + ':'] - - def _str_indent(self, doc, indent=4): - out = [] - for line in doc: - out += [' '*indent + line] - return out - - def _str_signature(self): - return [''] - if self['Signature']: - return ['``%s``' % self['Signature']] + [''] - else: - return [''] - - def _str_summary(self): - return self['Summary'] + [''] - - def _str_extended_summary(self): - return self['Extended Summary'] + [''] - - def _str_param_list(self, name): - out = [] - if self[name]: - out += self._str_field_list(name) - out += [''] - for param,param_type,desc in self[name]: - out += self._str_indent(['**%s** : %s' % (param.strip(), - param_type)]) - out += [''] - out += self._str_indent(desc,8) - out += [''] - return out - - def _str_section(self, name): - out = [] - if self[name]: - out += self._str_header(name) - out += [''] - content = textwrap.dedent("\n".join(self[name])).split("\n") - out += content - out += [''] - return out - - def _str_see_also(self, func_role): - out = [] - if self['See Also']: - see_also = super(SphinxDocString, self)._str_see_also(func_role) - out = ['.. seealso::', ''] - out += self._str_indent(see_also[2:]) - return out - - def _str_index(self): - idx = self['index'] - out = [] - if len(idx) == 0: - return out - - out += ['.. index:: %s' % idx.get('default','')] - for section, references in idx.iteritems(): - if section == 'default': - continue - elif section == 'refguide': - out += [' single: %s' % (', '.join(references))] - else: - out += [' %s: %s' % (section, ','.join(references))] - return out - - def _str_references(self): - out = [] - if self['References']: - out += self._str_header('References') - if isinstance(self['References'], str): - self['References'] = [self['References']] - out.extend(self['References']) - out += [''] - return out - - def __str__(self, indent=0, func_role="func"): - out = [] - out += self._str_signature() - out += self._str_index() + [''] - out += self._str_summary() - out += self._str_extended_summary() - for param_list in ('Parameters', 'Attributes', 'Methods', - 'Returns','Raises'): - out += self._str_param_list(param_list) - out += self._str_see_also("obj") - out += self._str_section('Notes') - out += self._str_references() - out += self._str_section('Examples') - out = self._str_indent(out,indent) - return '\n'.join(out) - -class SphinxFunctionDoc(SphinxDocString, FunctionDoc): - pass - -class SphinxClassDoc(SphinxDocString, ClassDoc): - pass diff --git a/docs/source/sphinxext/numpydoc.py b/docs/source/sphinxext/numpydoc.py deleted file mode 100644 index 6216a7af2..000000000 --- a/docs/source/sphinxext/numpydoc.py +++ /dev/null @@ -1,464 +0,0 @@ -import os, re, pydoc -from docscrape_sphinx import SphinxDocString, SphinxClassDoc, SphinxFunctionDoc -import inspect - -def mangle_docstrings(app, what, name, obj, options, lines, - reference_offset=[0]): - if what == 'module': - # Strip top title - title_re = re.compile(r'^\s*[#*=]{4,}\n[a-z0-9 -]+\n[#*=]{4,}\s*', - re.I|re.S) - lines[:] = title_re.sub('', "\n".join(lines)).split("\n") - else: - doc = get_doc_object(obj, what) - lines[:] = str(doc).split("\n") - - if app.config.numpydoc_edit_link and hasattr(obj, '__name__') and \ - obj.__name__: - v = dict(full_name=obj.__name__) - lines += [''] + (app.config.numpydoc_edit_link % v).split("\n") - - # replace reference numbers so that there are no duplicates - references = [] - for l in lines: - l = l.strip() - if l.startswith('.. ['): - try: - references.append(int(l[len('.. ['):l.index(']')])) - except ValueError: - print "WARNING: invalid reference in %s docstring" % name - - # Start renaming from the biggest number, otherwise we may - # overwrite references. - references.sort() - if references: - for i, line in enumerate(lines): - for r in references: - new_r = reference_offset[0] + r - lines[i] = lines[i].replace('[%d]_' % r, - '[%d]_' % new_r) - lines[i] = lines[i].replace('.. [%d]' % r, - '.. [%d]' % new_r) - - reference_offset[0] += len(references) - -def get_doc_object(obj, what=None): - if what is None: - if inspect.isclass(obj): - what = 'class' - elif inspect.ismodule(obj): - what = 'module' - elif callable(obj): - what = 'function' - else: - what = 'object' - if what == 'class': - return SphinxClassDoc(obj, '', func_doc=SphinxFunctionDoc) - elif what in ('function', 'method'): - return SphinxFunctionDoc(obj, '') - else: - return SphinxDocString(pydoc.getdoc(obj)) - -def mangle_signature(app, what, name, obj, options, sig, retann): - # Do not try to inspect classes that don't define `__init__` - if (inspect.isclass(obj) and - 'initializes x; see ' in pydoc.getdoc(obj.__init__)): - return '', '' - - if not (callable(obj) or hasattr(obj, '__argspec_is_invalid_')): return - if not hasattr(obj, '__doc__'): return - - doc = SphinxDocString(pydoc.getdoc(obj)) - if doc['Signature']: - sig = re.sub("^[^(]*", "", doc['Signature']) - return sig, '' - -def initialize(app): - try: - app.connect('autodoc-process-signature', mangle_signature) - except: - monkeypatch_sphinx_ext_autodoc() - - fn = app.config.numpydoc_phantom_import_file - if (fn and os.path.isfile(fn)): - print "[numpydoc] Phantom importing modules from", fn, "..." - import_phantom_module(fn) - -def setup(app): - app.connect('autodoc-process-docstring', mangle_docstrings) - app.connect('builder-inited', initialize) - app.add_config_value('numpydoc_phantom_import_file', None, True) - app.add_config_value('numpydoc_edit_link', None, True) - - app.add_directive('autosummary', autosummary_directive, 1, (0, 0, False)) - app.add_role('autolink', autolink_role) - -#------------------------------------------------------------------------------ -# .. autosummary:: -#------------------------------------------------------------------------------ -from docutils.statemachine import ViewList -from docutils import nodes - -import sphinx.addnodes, sphinx.roles -from sphinx.util import patfilter -import posixpath - -def autosummary_directive(dirname, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - """ - Pretty table containing short signatures and summaries of functions etc. - - autosummary also generates a (hidden) toctree:: node. - - """ - - # XXX: make the signatures and signature abbreviations optional - - names = [] - names += [x for x in content if x.strip()] - - result, warnings, titles = get_autosummary(names, state.document) - - node = nodes.paragraph() - state.nested_parse(result, 0, node) - - env = state.document.settings.env - suffix = env.config.source_suffix - all_docnames = env.found_docs.copy() - dirname = posixpath.dirname(env.docname) - - docnames = [] - doctitles = {} - for name in titles.keys(): - docname = 'generated/' + name - doctitles[docname] = "" - doctitles[docname + '.xhtml'] = "" - if docname.endswith(suffix): - docname = docname[:-len(suffix)] - docname = posixpath.normpath(posixpath.join(dirname, docname)) - if docname not in env.found_docs: - warnings.append(state.document.reporter.warning( - 'toctree references unknown document %r' % docname, - line=lineno)) - docnames.append(docname) - - tocnode = sphinx.addnodes.toctree() - tocnode['includefiles'] = docnames - tocnode['includetitles'] = doctitles - tocnode['maxdepth'] = -1 - tocnode['glob'] = None - - return warnings + node.children + [tocnode] - -def get_autosummary(names, document): - """ - Generate a proper table node for autosummary:: directive. - - Parameters - ---------- - names : list of str - Names of Python objects to be imported and added to the table. - document : document - Docutils document object - - """ - result = ViewList() - warnings = [] - titles = {} - - prefixes = [''] - prefixes.insert(0, document.settings.env.currmodule) - - rows = [] - - for name in names: - try: - obj, real_name = import_by_name(name, prefixes=prefixes) - except ImportError: - warnings.append(document.reporter.warning( - 'failed to import %s' % name)) - rows.append((":obj:`%s`" % name, "")) - continue - - doc = get_doc_object(obj) - - if doc['Summary']: - titles[real_name] = " ".join(doc['Summary']) - else: - titles[real_name] = "" - - col1 = ":obj:`%s`" % name - if doc['Signature']: - sig = re.sub('^[a-zA-Z_0-9.-]*', '', - doc['Signature'].replace('*', r'\*')) - if '=' in sig: - # abbreviate optional arguments - sig = re.sub(r', ([a-zA-Z0-9_]+)=', r'[, \1=', sig, count=1) - sig = re.sub(r'\(([a-zA-Z0-9_]+)=', r'([\1=', sig, count=1) - sig = re.sub(r'=[^,)]+,', ',', sig) - sig = re.sub(r'=[^,)]+\)$', '])', sig) - # shorten long strings - sig = re.sub(r'(\[.{16,16}[^,)]*?),.*?\]\)', r'\1, ...])', sig) - else: - sig = re.sub(r'(\(.{16,16}[^,)]*?),.*?\)', r'\1, ...)', sig) - col1 += " " + sig - col2 = titles[real_name] - - rows.append((col1, col2)) - - if not rows: - return result, warnings, titles - - max_name_len = max([len(x[0]) for x in rows]) - row_fmt = "%%-%ds %%s" % max_name_len - table_banner = ('='*max_name_len) + ' ' + '===============' - - result.append(table_banner, '') - for row in rows: - result.append(row_fmt % row, '') - result.append(table_banner, '') - result.append('', '') - - return result, warnings, titles - -def import_by_name(name, prefixes=[None]): - """ - Import a Python object that has the given name, under one of the prefixes. - - Parameters - ---------- - name : str - Name of a Python object, eg. 'numpy.ndarray.view' - prefixes : list of (str or None), optional - Prefixes to prepend to the name (None implies no prefix). - The first prefixed name that results to successful import is used. - - Returns - ------- - obj - The imported object - name - Name of the imported object (useful if `prefixes` was used) - - """ - for prefix in prefixes: - try: - if prefix: - prefixed_name = '.'.join([prefix, name]) - else: - prefixed_name = name - return _import_by_name(prefixed_name), prefixed_name - except ImportError: - pass - raise ImportError - -def _import_by_name(name): - """Import a Python object given its full name""" - try: - name_parts = name.split('.') - last_j = 0 - modname = None - for j in reversed(range(1, len(name_parts)+1)): - last_j = j - modname = '.'.join(name_parts[:j]) - try: - __import__(modname) - except ImportError: - continue - if modname in sys.modules: - break - - if last_j < len(name_parts): - obj = sys.modules[modname] - for obj_name in name_parts[last_j:]: - obj = getattr(obj, obj_name) - return obj - else: - return sys.modules[modname] - except (ValueError, ImportError, AttributeError, KeyError) as e: - raise ImportError(e) - -#------------------------------------------------------------------------------ -# :autolink: (smart default role) -#------------------------------------------------------------------------------ - -def autolink_role(typ, rawtext, etext, lineno, inliner, - options={}, content=[]): - """ - Smart linking role. - - Expands to ":obj:`text`" if `text` is an object that can be imported; - otherwise expands to "*text*". - """ - r = sphinx.roles.xfileref_role('obj', rawtext, etext, lineno, inliner, - options, content) - pnode = r[0][0] - - prefixes = [None] - #prefixes.insert(0, inliner.document.settings.env.currmodule) - try: - obj, name = import_by_name(pnode['reftarget'], prefixes) - except ImportError: - content = pnode[0] - r[0][0] = nodes.emphasis(rawtext, content[0].astext(), - classes=content['classes']) - return r - -#------------------------------------------------------------------------------ -# Monkeypatch sphinx.ext.autodoc to accept argspecless autodocs (Sphinx < 0.5) -#------------------------------------------------------------------------------ - -def monkeypatch_sphinx_ext_autodoc(): - global _original_format_signature - import sphinx.ext.autodoc - - if sphinx.ext.autodoc.format_signature is our_format_signature: - return - - print "[numpydoc] Monkeypatching sphinx.ext.autodoc ..." - _original_format_signature = sphinx.ext.autodoc.format_signature - sphinx.ext.autodoc.format_signature = our_format_signature - -def our_format_signature(what, obj): - r = mangle_signature(None, what, None, obj, None, None, None) - if r is not None: - return r[0] - else: - return _original_format_signature(what, obj) - -#------------------------------------------------------------------------------ -# Creating 'phantom' modules from an XML description -#------------------------------------------------------------------------------ -import imp, sys, compiler, types - -def import_phantom_module(xml_file): - """ - Insert a fake Python module to sys.modules, based on a XML file. - - The XML file is expected to conform to Pydocweb DTD. The fake - module will contain dummy objects, which guarantee the following: - - - Docstrings are correct. - - Class inheritance relationships are correct (if present in XML). - - Function argspec is *NOT* correct (even if present in XML). - Instead, the function signature is prepended to the function docstring. - - Class attributes are *NOT* correct; instead, they are dummy objects. - - Parameters - ---------- - xml_file : str - Name of an XML file to read - - """ - import lxml.etree as etree - - object_cache = {} - - tree = etree.parse(xml_file) - root = tree.getroot() - - # Sort items so that - # - Base classes come before classes inherited from them - # - Modules come before their contents - all_nodes = dict([(n.attrib['id'], n) for n in root]) - - def _get_bases(node, recurse=False): - bases = [x.attrib['ref'] for x in node.findall('base')] - if recurse: - j = 0 - while True: - try: - b = bases[j] - except IndexError: break - if b in all_nodes: - bases.extend(_get_bases(all_nodes[b])) - j += 1 - return bases - - type_index = ['module', 'class', 'callable', 'object'] - - def base_cmp(a, b): - x = cmp(type_index.index(a.tag), type_index.index(b.tag)) - if x != 0: return x - - if a.tag == 'class' and b.tag == 'class': - a_bases = _get_bases(a, recurse=True) - b_bases = _get_bases(b, recurse=True) - x = cmp(len(a_bases), len(b_bases)) - if x != 0: return x - if a.attrib['id'] in b_bases: return -1 - if b.attrib['id'] in a_bases: return 1 - - return cmp(a.attrib['id'].count('.'), b.attrib['id'].count('.')) - - nodes = root.getchildren() - nodes.sort(base_cmp) - - # Create phantom items - for node in nodes: - name = node.attrib['id'] - doc = (node.text or '').decode('string-escape') + "\n" - if doc == "\n": doc = "" - - # create parent, if missing - parent = name - while True: - parent = '.'.join(parent.split('.')[:-1]) - if not parent: break - if parent in object_cache: break - obj = imp.new_module(parent) - object_cache[parent] = obj - sys.modules[parent] = obj - - # create object - if node.tag == 'module': - obj = imp.new_module(name) - obj.__doc__ = doc - sys.modules[name] = obj - elif node.tag == 'class': - bases = [object_cache[b] for b in _get_bases(node) - if b in object_cache] - bases.append(object) - init = lambda self: None - init.__doc__ = doc - obj = type(name, tuple(bases), {'__doc__': doc, '__init__': init}) - obj.__name__ = name.split('.')[-1] - elif node.tag == 'callable': - funcname = node.attrib['id'].split('.')[-1] - argspec = node.attrib.get('argspec') - if argspec: - argspec = re.sub('^[^(]*', '', argspec) - doc = "%s%s\n\n%s" % (funcname, argspec, doc) - obj = lambda: 0 - obj.__argspec_is_invalid_ = True - obj.func_name = funcname - obj.__name__ = name - obj.__doc__ = doc - if inspect.isclass(object_cache[parent]): - obj.__objclass__ = object_cache[parent] - else: - class Dummy(object): pass - obj = Dummy() - obj.__name__ = name - obj.__doc__ = doc - if inspect.isclass(object_cache[parent]): - obj.__get__ = lambda: None - object_cache[name] = obj - - if parent: - if inspect.ismodule(object_cache[parent]): - obj.__module__ = parent - setattr(object_cache[parent], name.split('.')[-1], obj) - - # Populate items - for node in root: - obj = object_cache.get(node.attrib['id']) - if obj is None: continue - for ref in node.findall('ref'): - if node.tag == 'class': - if ref.attrib['ref'].startswith(node.attrib['id'] + '.'): - setattr(obj, ref.attrib['name'], - object_cache.get(ref.attrib['ref'])) - else: - setattr(obj, ref.attrib['name'], - object_cache.get(ref.attrib['ref'])) diff --git a/docs/source/sphinxext/traitsdoc.py b/docs/source/sphinxext/traitsdoc.py deleted file mode 100644 index 01c6dacf4..000000000 --- a/docs/source/sphinxext/traitsdoc.py +++ /dev/null @@ -1,141 +0,0 @@ -import inspect -import os -import pydoc - -import docscrape -from docscrape_sphinx import SphinxClassDoc, SphinxFunctionDoc -import numpydoc -import comment_eater - -class SphinxTraitsDoc(SphinxClassDoc): - def __init__(self, cls, modulename='', func_doc=SphinxFunctionDoc): - if not inspect.isclass(cls): - raise ValueError("Initialise using a class. Got %r" % cls) - self._cls = cls - - if modulename and not modulename.endswith('.'): - modulename += '.' - self._mod = modulename - self._name = cls.__name__ - self._func_doc = func_doc - - docstring = pydoc.getdoc(cls) - docstring = docstring.split('\n') - - # De-indent paragraph - try: - indent = min(len(s) - len(s.lstrip()) for s in docstring - if s.strip()) - except ValueError: - indent = 0 - - for n,line in enumerate(docstring): - docstring[n] = docstring[n][indent:] - - self._doc = docscrape.Reader(docstring) - self._parsed_data = { - 'Signature': '', - 'Summary': '', - 'Description': [], - 'Extended Summary': [], - 'Parameters': [], - 'Returns': [], - 'Raises': [], - 'Warns': [], - 'Other Parameters': [], - 'Traits': [], - 'Methods': [], - 'See Also': [], - 'Notes': [], - 'References': '', - 'Example': '', - 'Examples': '', - 'index': {} - } - - self._parse() - - def _str_summary(self): - return self['Summary'] + [''] - - def _str_extended_summary(self): - return self['Description'] + self['Extended Summary'] + [''] - - def __str__(self, indent=0, func_role="func"): - out = [] - out += self._str_signature() - out += self._str_index() + [''] - out += self._str_summary() - out += self._str_extended_summary() - for param_list in ('Parameters', 'Traits', 'Methods', - 'Returns','Raises'): - out += self._str_param_list(param_list) - out += self._str_see_also("obj") - out += self._str_section('Notes') - out += self._str_references() - out += self._str_section('Example') - out += self._str_section('Examples') - out = self._str_indent(out,indent) - return '\n'.join(out) - -def looks_like_issubclass(obj, classname): - """ Return True if the object has a class or superclass with the given class - name. - - Ignores old-style classes. - """ - t = obj - if t.__name__ == classname: - return True - for klass in t.__mro__: - if klass.__name__ == classname: - return True - return False - -def get_doc_object(obj, what=None): - if what is None: - if inspect.isclass(obj): - what = 'class' - elif inspect.ismodule(obj): - what = 'module' - elif callable(obj): - what = 'function' - else: - what = 'object' - if what == 'class': - doc = SphinxTraitsDoc(obj, '', func_doc=numpydoc.SphinxFunctionDoc) - if looks_like_issubclass(obj, 'HasTraits'): - for name, trait, comment in comment_eater.get_class_traits(obj): - # Exclude private traits. - if not name.startswith('_'): - doc['Traits'].append((name, trait, comment.splitlines())) - return doc - elif what in ('function', 'method'): - return numpydoc.SphinxFunctionDoc(obj, '') - else: - return numpydoc.SphinxDocString(pydoc.getdoc(obj)) - -def initialize(app): - try: - app.connect('autodoc-process-signature', numpydoc.mangle_signature) - except: - numpydoc.monkeypatch_sphinx_ext_autodoc() - - # Monkeypatch numpydoc - numpydoc.get_doc_object = get_doc_object - - fn = app.config.numpydoc_phantom_import_file - if (fn and os.path.isfile(fn)): - print "[numpydoc] Phantom importing modules from", fn, "..." - numpydoc.import_phantom_module(fn) - -def setup(app): - app.connect('autodoc-process-docstring', numpydoc.mangle_docstrings) - app.connect('builder-inited', initialize) - app.add_config_value('numpydoc_phantom_import_file', None, True) - app.add_config_value('numpydoc_edit_link', None, True) - - app.add_directive('autosummary', numpydoc.autosummary_directive, 1, (0, 0, False)) - app.add_role('autolink', numpydoc.autolink_role) - - diff --git a/docs/source/user_manual/chaco_tutorial.rst b/docs/source/user_manual/chaco_tutorial.rst index 865b919ce..e6331fe9f 100644 --- a/docs/source/user_manual/chaco_tutorial.rst +++ b/docs/source/user_manual/chaco_tutorial.rst @@ -724,16 +724,16 @@ and a corresponding ``Item`` in the Traits UI View :: By default, an ``Enum`` trait will be displayed as a drop-down. In the constructor, we create a dictionary that maps the data names to actual -numpy arrays: :: +numpy arrays:: # jn is the Bessel function - self.data = {“jn0”: jn(0, x), - “jn1”: jn(1, x), - “jn2”: jn(2, x)} + self.data = {"jn0": jn(0, x), + "jn1": jn(1, x), + "jn2": jn(2, x)} -When we initialize the ArrayPlotData, we’ll set ``y`` to the ``jn0`` array. :: +When we initialize the ArrayPlotData, we’ll set ``y`` to the ``jn0`` array:: - self.plotdata = ArrayPlotData(x = x, y = self.data[“jn0”]) + self.plotdata = ArrayPlotData(x = x, y = self.data["jn0"]) plot = Plot(self.plotdata) Note that we are storing a reference to the ``plotdata`` object.