Improve doc coverage of GUI features

[jni]

Currently our narrative docs are task oriented, which is great, but they are not aiming to provide exhaustive coverage of all the things you can do in the viewer from the GUI. This would be the "reference" section of the diataxis section — currently we have reserved that for the API docs, but this leaves GUI-primary users in a lurch, particularly until we achieve GUI-API feature parity. It would be good to systematically cover everything we can adjust in the GUI somehow. (Probably good to start with napari/napari#5959.)

[jni]

See also #93

[psobolewskiPhD]

related issues:
#13
#38
#37
#155

[dalthviz]

Hi there, maybe not completly related to this but just in case, I was checking and running coverage.py when building the docs (cleaning any previous build first) with something like:

 coverage run --source=napari._qt --omit="*/_tests/*" -m sphinx.cmd.build -b html docs/ docs/_build -D sphinx_gallery_conf.examples_dirs=../../napari/examples

Can give you access to a coverage report (running coverage report) regarding Qt related code (in this specific case code under the napari/_qt) that is touched when builiding the docs. It looks something like the following:

Example generated report

Name                                                                                                  Stmts   Miss  Cover
-------------------------------------------------------------------------------------------------------------------------
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\__init__.py                                        33     20    39%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\_qapp_model\__init__.py                             2      0   100%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\_qapp_model\_menus.py                               7      1    86%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\_qapp_model\qactions\__init__.py                   25      2    92%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\_qapp_model\qactions\_file.py                      24      7    71%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\_qapp_model\qactions\_help.py                      15      2    87%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\_qapp_model\qactions\_view.py                      18      1    94%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\code_syntax_highlight.py                           44     32    27%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\containers\__init__.py                              8      0   100%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\containers\_base_item_model.py                     94     19    80%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\containers\_base_item_view.py                      61     11    82%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\containers\_factory.py                             27     15    44%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\containers\_layer_delegate.py                     128     69    46%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\containers\qt_layer_list.py                        39     12    69%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\containers\qt_layer_model.py                       59     17    71%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\containers\qt_list_model.py                        38     23    39%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\containers\qt_list_view.py                         20      3    85%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\containers\qt_tree_model.py                        87     61    30%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\containers\qt_tree_view.py                         32     17    47%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\dialogs\__init__.py                                 0      0   100%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\dialogs\confirm_close_dialog.py                    45     38    16%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\dialogs\preferences_dialog.py                     123    101    18%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\dialogs\qt_about.py                                49     37    24%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\dialogs\qt_activity_dialog.py                     150     66    56%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\dialogs\qt_modal.py                                62     42    32%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\dialogs\qt_notification.py                        243    196    19%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\dialogs\qt_plugin_report.py                       105     89    15%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\dialogs\qt_reader_dialog.py                        95     78    18%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\dialogs\screenshot_dialog.py                       29     19    34%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\experimental\__init__.py                            0      0   100%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\experimental\qt_poll.py                            42     42     0%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\layer_controls\__init__.py                          2      0   100%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\layer_controls\qt_colormap_combobox.py             34      9    74%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\layer_controls\qt_image_controls.py               196     30    85%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\layer_controls\qt_image_controls_base.py          150     50    67%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\layer_controls\qt_labels_controls.py              282     38    87%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\layer_controls\qt_layer_controls_base.py           79      7    91%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\layer_controls\qt_layer_controls_container.py      61      1    98%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\layer_controls\qt_points_controls.py              162     37    77%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\layer_controls\qt_shapes_controls.py              149     15    90%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\layer_controls\qt_surface_controls.py              31      2    94%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\layer_controls\qt_tracks_controls.py              108     12    89%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\layer_controls\qt_vectors_controls.py             150     33    78%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\menus\__init__.py                                   4      0   100%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\menus\_util.py                                     73     60    18%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\menus\debug_menu.py                                44     30    32%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\menus\plugins_menu.py                              87     45    48%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\menus\window_menu.py                               11      2    82%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\perf\__init__.py                                    0      0   100%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\perf\qt_event_tracing.py                           36     36     0%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\perf\qt_performance.py                             70     53    24%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\qt_event_filters.py                                12      6    50%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\qt_event_loop.py                                  146     43    71%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\qt_main_window.py                                 650    232    64%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\qt_resources\__init__.py                           27      6    78%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\qt_resources\_svg.py                               38      7    82%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\qt_viewer.py                                      459    225    51%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\qthreading.py                                      94     28    70%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\utils.py                                          145     50    66%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\widgets\__init__.py                                 0      0   100%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\widgets\_slider_compat.py                           7      0   100%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\widgets\qt_color_swatch.py                        126     39    69%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\widgets\qt_dict_table.py                           63     63     0%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\widgets\qt_dims.py                                162     28    83%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\widgets\qt_dims_slider.py                         372    156    58%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\widgets\qt_dims_sorter.py                          61     41    33%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\widgets\qt_extension2reader.py                    160    160     0%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\widgets\qt_font_size.py                            31     31     0%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\widgets\qt_highlight_preview.py                   243    243     0%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\widgets\qt_keyboard_settings.py                   315    315     0%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\widgets\qt_message_popup.py                        22     22     0%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\widgets\qt_mode_buttons.py                         30      1    97%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\widgets\qt_plugin_sorter.py                       179    179     0%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\widgets\qt_progress_bar.py                         69     47    32%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\widgets\qt_range_slider_popup.py                   22     15    32%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\widgets\qt_scrollbar.py                            34     26    24%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\widgets\qt_size_preview.py                        148    148     0%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\widgets\qt_spinbox.py                              14      7    50%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\widgets\qt_splash_screen.py                        10     10     0%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\widgets\qt_theme_sample.py                        109    109     0%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\widgets\qt_tooltip.py                               8      4    50%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\widgets\qt_viewer_buttons.py                      182     89    51%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\widgets\qt_viewer_dock_widget.py                  181     16    91%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\widgets\qt_viewer_status_bar.py                   119     25    79%
E:\Acer\Documentos\Quansight\Napari\napari\napari\_qt\widgets\qt_welcome.py                              90     16    82%
-------------------------------------------------------------------------------------------------------------------------
TOTAL                                                                                                  7761   3867    50%

Also, running coverage html can give you some further details of the coverage per file/line:

[jni]

Very cool @dalthviz!

I wonder if we should add a section to the docs like "development tips and tricks" to compile this sort of command. This wouldn't have to be very organised or anything, just an FAQ-style page, which would contain little tidbits like this one that our developers might like to share.