Add initial UI sections docs pages and script for generation #114

dalthviz · 2023-02-23T19:13:55Z

Description

Initial structure for UI sections documentation, support to render mermaid diagrams inside the documentation and a script to generate the UI sections documentation pages

Type of change

Adds new content page(s)

References

closes #93

Final checklist:

My PR is the minimum possible work for the desired functionality
I have commented my code, particularly in hard-to-understand areas
I have added alt text to new images included in this PR

…table is unavailable when running UI sections update script

… generated files

psobolewskiPhD · 2023-03-04T09:45:14Z

I think this is great! I have a hard time figuring out where in the code base something is—like recently wanting to change the behavior of the visibility eye button.
While the maps are quite complex for me, the tree structure shows me quite clearly what parts of the codebase are linked together for those key UI elements.
(Also, I love your plugin for exploring the GUI!!)

dalthviz · 2023-03-06T16:53:50Z

Thanks for the feedback @psobolewskiPhD ! Yes, sometimes the diagrams are still a little bit convoluted, could it be worthy to try to group the nodes in subgraphs in some way to help with that?

Happy to hear that you checked out the plugin and the directory layout helps!

dalthviz · 2023-03-06T18:52:54Z

Just in case, experimenting a little bit with mermaid subgraphs and using the directory where the detected module is located, the diagram could look something like this (for example for the Applications menus page):

Application menus

Dependencies diagram (related `napari` modules)

graph LR
	napari._qt(napari._qt)
	napari._qt --> napari._qt.qt_main_window
	click napari._qt "https://github.com/napari/napari/tree/main/napari/_qt/__init__.py" _blank
	napari._qt._qapp_model.qactions(napari._qt._qapp_model.qactions)
	napari._qt._qapp_model.qactions --> napari._qt.qt_main_window
	click napari._qt._qapp_model.qactions "https://github.com/napari/napari/tree/main/napari/_qt/_qapp_model/qactions/__init__.py" _blank
	napari._qt.dialogs.preferences_dialog(napari._qt.dialogs.preferences_dialog)
	click napari._qt.dialogs.preferences_dialog "https://github.com/napari/napari/tree/main/napari/_qt/dialogs/preferences_dialog.py" _blank
	napari._qt.dialogs.qt_plugin_dialog(napari._qt.dialogs.qt_plugin_dialog)
	napari._qt.dialogs.qt_plugin_dialog --> napari._qt.qt_resources
	napari._qt.dialogs.qt_plugin_dialog --> napari._qt.widgets
	click napari._qt.dialogs.qt_plugin_dialog "https://github.com/napari/napari/tree/main/napari/_qt/dialogs/qt_plugin_dialog.py" _blank
	napari._qt.dialogs.qt_plugin_report(napari._qt.dialogs.qt_plugin_report)
	click napari._qt.dialogs.qt_plugin_report "https://github.com/napari/napari/tree/main/napari/_qt/dialogs/qt_plugin_report.py" _blank
	napari._qt.dialogs.qt_reader_dialog(napari._qt.dialogs.qt_reader_dialog)
	click napari._qt.dialogs.qt_reader_dialog "https://github.com/napari/napari/tree/main/napari/_qt/dialogs/qt_reader_dialog.py" _blank
	napari._qt.dialogs.screenshot_dialog(napari._qt.dialogs.screenshot_dialog)
	click napari._qt.dialogs.screenshot_dialog "https://github.com/napari/napari/tree/main/napari/_qt/dialogs/screenshot_dialog.py" _blank
	napari._qt.menus(napari._qt.menus)
	napari._qt.menus --> napari._qt.menus.debug_menu
	napari._qt.menus --> napari._qt.menus.file_menu
	napari._qt.menus --> napari._qt.menus.plugins_menu
	napari._qt.menus --> napari._qt.menus.window_menu
	click napari._qt.menus "https://github.com/napari/napari/tree/main/napari/_qt/menus/__init__.py" _blank
	napari._qt.menus._util(napari._qt.menus._util)
	click napari._qt.menus._util "https://github.com/napari/napari/tree/main/napari/_qt/menus/_util.py" _blank
	napari._qt.menus.debug_menu(napari._qt.menus.debug_menu)
	napari._qt.menus.debug_menu --> napari._qt.menus._util
	napari._qt.menus.debug_menu --> napari._qt.qt_main_window
	click napari._qt.menus.debug_menu "https://github.com/napari/napari/tree/main/napari/_qt/menus/debug_menu.py" _blank
	napari._qt.menus.file_menu(napari._qt.menus.file_menu)
	napari._qt.menus.file_menu --> napari._qt.dialogs.preferences_dialog
	napari._qt.menus.file_menu --> napari._qt.dialogs.qt_reader_dialog
	napari._qt.menus.file_menu --> napari._qt.dialogs.screenshot_dialog
	napari._qt.menus.file_menu --> napari._qt.menus._util
	napari._qt.menus.file_menu --> napari._qt.qt_main_window
	click napari._qt.menus.file_menu "https://github.com/napari/napari/tree/main/napari/_qt/menus/file_menu.py" _blank
	napari._qt.menus.plugins_menu(napari._qt.menus.plugins_menu)
	napari._qt.menus.plugins_menu --> napari._qt.dialogs.qt_plugin_dialog
	napari._qt.menus.plugins_menu --> napari._qt.dialogs.qt_plugin_report
	napari._qt.menus.plugins_menu --> napari._qt.menus._util
	napari._qt.menus.plugins_menu --> napari._qt.qt_main_window
	click napari._qt.menus.plugins_menu "https://github.com/napari/napari/tree/main/napari/_qt/menus/plugins_menu.py" _blank
	napari._qt.menus.window_menu(napari._qt.menus.window_menu)
	napari._qt.menus.window_menu --> napari._qt.menus._util
	napari._qt.menus.window_menu --> napari._qt.qt_main_window
	click napari._qt.menus.window_menu "https://github.com/napari/napari/tree/main/napari/_qt/menus/window_menu.py" _blank
	napari._qt.qt_main_window(napari._qt.qt_main_window)
	napari._qt.qt_main_window --> napari._qt._qapp_model.qactions
	napari._qt.qt_main_window --> napari._qt.menus
	napari._qt.qt_main_window --> napari._qt.qt_resources
	napari._qt.qt_main_window --> napari._qt.widgets
	click napari._qt.qt_main_window "https://github.com/napari/napari/tree/main/napari/_qt/qt_main_window.py" _blank
	napari._qt.qt_resources(napari._qt.qt_resources)
	click napari._qt.qt_resources "https://github.com/napari/napari/tree/main/napari/_qt/qt_resources/__init__.py" _blank
	napari._qt.widgets(napari._qt.widgets)
	click napari._qt.widgets "https://github.com/napari/napari/tree/main/napari/_qt/widgets/__init__.py" _blank
	subgraph module.napari[napari]
		 napari._qt
	end
	class module.napari subgraphs
	subgraph module.napari._qt._qapp_model[napari._qt._qapp_model]
		 napari._qt._qapp_model.qactions
	end
	class module.napari._qt._qapp_model subgraphs
	subgraph module.napari._qt.dialogs[napari._qt.dialogs]
		 napari._qt.dialogs.preferences_dialog
		 napari._qt.dialogs.qt_plugin_dialog
		 napari._qt.dialogs.qt_plugin_report
		 napari._qt.dialogs.qt_reader_dialog
		 napari._qt.dialogs.screenshot_dialog
	end
	class module.napari._qt.dialogs subgraphs
	subgraph module.napari._qt[napari._qt]
		 napari._qt.menus
		 napari._qt.qt_main_window
		 napari._qt.qt_resources
		 napari._qt.widgets
	end
	class module.napari._qt subgraphs
	subgraph module.napari._qt.menus[napari._qt.menus]
		 napari._qt.menus._util
		 napari._qt.menus.debug_menu
		 napari._qt.menus.file_menu
		 napari._qt.menus.plugins_menu
		 napari._qt.menus.window_menu
	end
	class module.napari._qt.menus subgraphs
	classDef subgraphs fill:white,strock:black,color:black;	classDef default fill:#00c3ff,color:black;
	linkStyle default stroke:#00c3ff
	classDef external fill:#ffa600,color:black;

Source code directory layout (related to modules inside `napari`)

napari/
└─_qt/
  ├─dialogs/
  │ ├─preferences_dialog.py
  │ ├─qt_plugin_dialog.py
  │ ├─qt_plugin_report.py
  │ ├─qt_reader_dialog.py
  │ └─screenshot_dialog.py
  ├─menus/
  │ ├─debug_menu.py
  │ ├─file_menu.py
  │ ├─plugins_menu.py
  │ ├─window_menu.py
  │ ├─_util.py
  │ └─__init__.py
  ├─qt_main_window.py
  ├─qt_resources/
  │ └─__init__.py
  ├─widgets/
  │ └─__init__.py
  ├─_qapp_model/
  │ └─qactions/
  │   └─__init__.py
  └─__init__.py

psobolewskiPhD · 2023-03-06T19:07:10Z

That looks cool! are the zoom/pan controls a markdown thing only?

dalthviz · 2023-03-06T19:15:38Z

Awesome! And regarding the zoom controls I think is something GitHub added when it is rendering mermaid diagrams, not totally sure if there is a way to add that to the generated documentation but I can check 👍

dalthviz · 2023-03-08T17:40:58Z

Did a little exploration of how to add zoom capabilities to the diagram rendering and I got this:

This uses d3 to enable the zoom

psobolewskiPhD · 2023-03-26T18:06:46Z

Really dig this!
Slightly off topic: I think that we need to rethink our top-level menus to make dev/contributing stuff easier to find, because Community is probably not too logical for this?
cc: @melissawm
Maybe we need a top level thing for dev/contriuting that folds in the API reference and other dev centric things.

dalthviz · 2023-04-10T16:18:28Z

Just in case, I was checking the top-level navigation of the page and seems like the API reference part could be though as part of the Usage section (is kind of a reference for the public API of napari which could help users use napari programatically from what I understand)? Maybe the idea to have API reference as a top-level entry is for easy access? Also, after checking, I think too it could make sense to add a top-level navigation entry with the Contributing resources section for discoverability 👍 Anyhow, maybe a new issue should be created to better discuss these sections organization ideas?

melissawm · 2024-10-24T14:39:30Z

@dalthviz is this ready for another round of reviews?

dalthviz · 2024-10-24T15:24:20Z

Yep @melissawm ! 👍

psobolewskiPhD · 2024-12-18T21:15:02Z

This is super cool! But I'm not getting the ability to zoom at least with the CircleCI docs
https://output.circle-artifacts.com/output/job/4c5e2695-c613-4305-9aaf-a74f0a5002b6/artifacts/0/docs/docs/_build/html/developers/architecture/ui_sections/application_status_bar_ui.html

Tried in Safari and Chrome -- am I missing something?

dalthviz · 2024-12-18T22:41:54Z

Seems like something changed with the latest sphinxcontrib.mermaid extension release since constraining the extension version to be <1.0.0 makes things work 🤔

dalthviz · 2024-12-19T19:21:03Z

@psobolewskiPhD I think I was able to change the mermaid related config for it to work again (nodes should show names, be clickable and you should be able to pan and zoom the diagrams). Let me know if you still see issues!

psobolewskiPhD · 2024-12-20T21:49:24Z

Awesome! Yeah pan and zoom work great now.
Not a blocker, but the way our layout works is that making the window wider never makes the diagram bigger. It would be nice to have a way to pop it to a new tab/window to be able to make it larger.
Any ideas how that could be done? Could save it for a followup, but I think it would be very valuable to get the most out of the diagrams.

psobolewskiPhD · 2024-12-20T21:51:33Z

Oh! And what do you think of linking to your awesome plugin on the UI sections landing page
https://github.com/dalthviz/napari-ui-tracer

dalthviz · 2024-12-23T17:32:47Z

Not a blocker, but the way our layout works is that making the window wider never makes the diagram bigger. It would be nice to have a way to pop it to a new tab/window to be able to make it larger.
Any ideas how that could be done?

Maybe some custom code could enable doing something like opening the diagram in a new window indeed. As a quick check, something like the following could be achieved (kind of like taking a snapshot of the current zoom level/part of the diagram currently being viewed and showing that in a new tab/window):

Note that the preview above was done by running some custom code (https://stackoverflow.com/a/56110734) + adding a new HTML node (click link) via the browser development tooling to trigger the code.

Oh! And what do you think of linking to your awesome plugin on the UI sections landing page
https://github.com/dalthviz/napari-ui-tracer

If that could be useful to have over the docs sure 👍 Is there any phrasing that should be used for the link? Maybe something like:

Also, a plugin to inspect how specific UI elements/widgets are defined
over the napari source code is available (https://github.com/dalthviz/napari-ui-tracer)

?

psobolewskiPhD · 2024-12-24T02:26:10Z

I like that phrasing @dalthviz !
Let's open an issue for the pop-out of the diagrams.

Initial UI sections docs generation

063119a

github-actions bot assigned dalthviz Feb 23, 2023

github-actions bot added the documentation Improvements or additions to documentation label Feb 23, 2023

dalthviz changed the title ~~Add initial UI sections docs generation~~ Add initial UI sections docs pages and script Feb 23, 2023

dalthviz added 2 commits February 23, 2023 14:18

Fix UI sections script call

85e4dc5

Add graphviz installation step to CI. Catch OSError if graphviz execu…

3bfadc4

…table is unavailable when running UI sections update script

github-actions bot added the task label Feb 24, 2023

dalthviz added 2 commits February 24, 2023 11:56

Use flag to not use dot executable instead of adding it to CI. Remove…

02debe7

… generated files

Update .gitignore for UI sections pages generation

f7e46e8

github-actions bot removed the task label Feb 24, 2023

dalthviz added 2 commits February 24, 2023 12:11

Use no-output flag and undo some changes

be02a44

Use no-output flag inside the script

772f4d2

dalthviz changed the title ~~Add initial UI sections docs pages and script~~ Add initial UI sections docs pages and script for generation Feb 24, 2023

Fix index link and links inside diagrams

277f6df

dalthviz marked this pull request as ready for review February 24, 2023 18:24

dalthviz added 4 commits March 6, 2023 14:18

Divide diagrams in subgraphs

c0115bb

Merge branch 'main' into issue_93

4afe56a

Test using d3 to add zoom for mermaid diagrams

7045d08

Change d3 zoom addition approach

82fd5e6

dalthviz added 2 commits March 10, 2023 12:03

Add docstring to functions and accesibility config to mermaid diagrams

a3c6a77

Merge branch 'main' into issue_93

470b01b

dalthviz mentioned this pull request Mar 16, 2023

Add documentation mapping visual UI with code structure, modules and classes #93

Open

dalthviz added 6 commits August 26, 2024 13:53

Update layer controls generation args

41e8cf1

Merge branch 'main' into issue_93

185075a

Update layer list args and remove general unused args

83ba1ad

Update viewer args

61934c9

Update console args

3d5c161

Update dialog args and add external modules subgraph

be943eb

dalthviz marked this pull request as ready for review August 27, 2024 19:57

Merge branch 'main' into issue_93

185ced5

Merge branch 'main' into issue_93

a5f93fa

psobolewskiPhD self-requested a review November 8, 2024 00:42

dalthviz mentioned this pull request Dec 6, 2024

Layer controls widgets refactor napari/napari#7355

Open

Merge branch 'main' into issue_93

1daa207

dalthviz closed this Dec 18, 2024

dalthviz reopened this Dec 18, 2024

dalthviz added 2 commits December 18, 2024 16:30

Testing

3cfe160

Testing

1817430

dalthviz added 4 commits December 19, 2024 09:37

Test new default mermaid version

14e5997

Check mermaid extension version update

c8780f7

Trying to disable elk support

c967797

Pass specific mermaid version

5e1df11

Merge branch 'main' into issue_93

179d031

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add initial UI sections docs pages and script for generation #114

Add initial UI sections docs pages and script for generation #114

dalthviz commented Feb 23, 2023 •

edited

Loading

psobolewskiPhD commented Mar 4, 2023

dalthviz commented Mar 6, 2023

dalthviz commented Mar 6, 2023

psobolewskiPhD commented Mar 6, 2023

dalthviz commented Mar 6, 2023

dalthviz commented Mar 8, 2023

psobolewskiPhD commented Mar 26, 2023

dalthviz commented Apr 10, 2023

melissawm commented Oct 24, 2024

dalthviz commented Oct 24, 2024

psobolewskiPhD commented Dec 18, 2024

dalthviz commented Dec 18, 2024

dalthviz commented Dec 19, 2024

psobolewskiPhD commented Dec 20, 2024

psobolewskiPhD commented Dec 20, 2024

dalthviz commented Dec 23, 2024

psobolewskiPhD commented Dec 24, 2024

Add initial UI sections docs pages and script for generation #114

Are you sure you want to change the base?

Add initial UI sections docs pages and script for generation #114

Conversation

dalthviz commented Feb 23, 2023 • edited Loading

Description

Type of change

References

Final checklist:

psobolewskiPhD commented Mar 4, 2023

dalthviz commented Mar 6, 2023

dalthviz commented Mar 6, 2023

Application menus

Dependencies diagram (related napari modules)

Source code directory layout (related to modules inside napari)

psobolewskiPhD commented Mar 6, 2023

dalthviz commented Mar 6, 2023

dalthviz commented Mar 8, 2023

psobolewskiPhD commented Mar 26, 2023

dalthviz commented Apr 10, 2023

melissawm commented Oct 24, 2024

dalthviz commented Oct 24, 2024

psobolewskiPhD commented Dec 18, 2024

dalthviz commented Dec 18, 2024

dalthviz commented Dec 19, 2024

psobolewskiPhD commented Dec 20, 2024

psobolewskiPhD commented Dec 20, 2024

dalthviz commented Dec 23, 2024

psobolewskiPhD commented Dec 24, 2024

dalthviz commented Feb 23, 2023 •

edited

Loading

Dependencies diagram (related `napari` modules)

Source code directory layout (related to modules inside `napari`)