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

rahulporuri · 2020-12-10T11:41:20Z

This PR improves documentation for the following submodules - pyface.tasks.action and pyface.action submodules.

Specifically,

the api modules now have a module docstring, which gets used in the autogenerated API docs
the in-code comments for traits have been updated such that sphinx picks them up
two spelling mistakes have been fixed.

specifically, the pyface.tasks.action and pyface.action submodules. Additionally, some of the comments on traits in code have been updated so that they get picked up by sphinx and get documented in the autogenerated API docs Finally, two spelling corrections have been made.

modified: pyface/action/menu_bar_manager.py modified: pyface/action/menu_manager.py modified: pyface/action/status_bar_manager.py modified: pyface/action/tool_bar_manager.py modified: pyface/action/tool_palette_manager.py

codecov-io · 2020-12-10T14:59:06Z

Codecov Report

Merging #843 (6921d15) into master (92ab736) will increase coverage by 0.14%.
The diff coverage is 96.55%.

@@            Coverage Diff             @@
##           master     #843      +/-   ##
==========================================
+ Coverage   41.15%   41.29%   +0.14%     
==========================================
  Files         522      522              
  Lines       28110    28126      +16     
  Branches     4251     4253       +2     
==========================================
+ Hits        11568    11614      +46     
+ Misses      16037    16015      -22     
+ Partials      505      497       -8

Impacted Files	Coverage Δ
pyface/action/action_event.py	`100.00% <ø> (ø)`
pyface/action/action_manager.py	`83.92% <ø> (ø)`
pyface/action/field_action.py	`95.00% <ø> (ø)`
pyface/tasks/action/listening_action.py	`0.00% <0.00%> (ø)`
pyface/tasks/action/schema.py	`87.93% <ø> (ø)`
pyface/tasks/action/schema_addition.py	`100.00% <ø> (ø)`
pyface/tasks/action/task_action.py	`60.00% <ø> (ø)`
pyface/tasks/action/task_action_controller.py	`52.94% <ø> (ø)`
pyface/tasks/action/task_action_manager_builder.py	`91.96% <ø> (ø)`
pyface/tasks/action/task_toggle_group.py	`48.97% <ø> (ø)`
... and 20 more

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 3ea7832...6921d15. Read the comment docs.

aaronayres35

LGTM, I built the docs and everything looked good. Just a couple comments

pyface/action/api.py

aaronayres35 · 2020-12-10T15:47:31Z

pyface/action/menu_bar_manager.py

+control.
+
+- :attr:`~.MenuBarManager`
+"""


When building the docs, these "- :attr:~.MenuBarManager" lines just show up as

MenuBarManager

Without any link. Not a suggested change now, but maybe as a future improvement, for toolkit specific things we could link to both implementations somehow? e.g. one link to docs for https://github.com/enthought/pyface/blob/master/pyface/ui/qt4/action/menu_bar_manager.py and another for wx

Without any link.

There is already an issue: #755
Note that Qt and Wx implementations don't necessarily have exactly the same definition. Cherry-picking the ones I know:
The enum definition for DataViewWidget looks like this in Qt:

pyface/pyface/ui/qt4/data_view/data_view_widget.py

Lines 100 to 104 in 3ea7832

#: What can be selected. Qt supports additional selection types.

selection_type = Enum("row", "column", "item")

#: How selections are modified. Qt supports turning off selections.

selection_mode = Enum("extended", "none", "single")

But it looks like this in Wx:

pyface/pyface/ui/wx/data_view/data_view_widget.py

Lines 42 to 46 in 3ea7832

#: What can be selected.

selection_type = Enum("row")

#: How selections are modified.

selection_mode = Enum("extended", "single")

We can't merge the two into one without having to pick one over another.
Another hard problem is the dependency on the toolkit while generating the doc. Some mocking (in doc config) may be needed, but that is not necessarily trivial either.

pyface/tasks/action/listening_action.py

pyface/action/api.py

pyface/tasks/action/api.py

pyface/action/api.py

kitchoi · 2020-12-10T16:16:03Z

pyface/action/menu_bar_manager.py

+control.
+
+- :attr:`~.MenuBarManager`
+"""


Without any link.

There is already an issue: #755
Note that Qt and Wx implementations don't necessarily have exactly the same definition. Cherry-picking the ones I know:
The enum definition for DataViewWidget looks like this in Qt:

pyface/pyface/ui/qt4/data_view/data_view_widget.py

Lines 100 to 104 in 3ea7832

#: What can be selected. Qt supports additional selection types.

selection_type = Enum("row", "column", "item")

#: How selections are modified. Qt supports turning off selections.

selection_mode = Enum("extended", "none", "single")

But it looks like this in Wx:

pyface/pyface/ui/wx/data_view/data_view_widget.py

Lines 42 to 46 in 3ea7832

#: What can be selected.

selection_type = Enum("row")

#: How selections are modified.

selection_mode = Enum("extended", "single")

We can't merge the two into one without having to pick one over another.
Another hard problem is the dependency on the toolkit while generating the doc. Some mocking (in doc config) may be needed, but that is not necessarily trivial either.

pyface/tasks/action/api.py

pyface/action/api.py

modified: pyface/action/api.py modified: pyface/tasks/action/api.py modified: pyface/tasks/action/listening_action.py

kitchoi

LGTM. Thank you!

pyface/action/api.py

rahulporuri mentioned this pull request Dec 10, 2020

Remove backwards compat module : pyface.tasks.action.listening_action #842

Closed

rahulporuri changed the title ~~Improve documentation for *.action submodules~~ Improve documentation for pyface.action and pyface.tasks.action submodules Dec 10, 2020

aaronayres35 approved these changes Dec 10, 2020

View reviewed changes

kitchoi reviewed Dec 10, 2020

View reviewed changes

CLN : Address review comments

17d0c82

modified: pyface/action/api.py modified: pyface/tasks/action/api.py modified: pyface/tasks/action/listening_action.py

kitchoi approved these changes Dec 10, 2020

View reviewed changes

kitchoi reviewed Dec 10, 2020

View reviewed changes

pyface/action/api.py Show resolved Hide resolved

rahulporuri merged commit d13b91f into master Dec 11, 2020

rahulporuri deleted the cln/minor-updates-to-action-submodules branch December 11, 2020 08:16

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

rahulporuri commented Dec 10, 2020

codecov-io commented Dec 10, 2020 •

edited

Loading

aaronayres35 left a comment

aaronayres35 Dec 10, 2020

kitchoi Dec 10, 2020

kitchoi Dec 10, 2020

kitchoi left a comment

	#: What can be selected. Qt supports additional selection types.
	selection_type = Enum("row", "column", "item")

	#: How selections are modified. Qt supports turning off selections.
	selection_mode = Enum("extended", "none", "single")

	#: What can be selected.
	selection_type = Enum("row")

	#: How selections are modified.
	selection_mode = Enum("extended", "single")

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

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

Conversation

rahulporuri commented Dec 10, 2020

codecov-io commented Dec 10, 2020 • edited Loading

Codecov Report

aaronayres35 left a comment

Choose a reason for hiding this comment

aaronayres35 Dec 10, 2020

Choose a reason for hiding this comment

kitchoi Dec 10, 2020

Choose a reason for hiding this comment

kitchoi Dec 10, 2020

Choose a reason for hiding this comment

kitchoi left a comment

Choose a reason for hiding this comment

codecov-io commented Dec 10, 2020 •

edited

Loading