diff --git a/doc/tools/devtools.md b/doc/tools/devtools.md index 58399568..5f8f9e29 100644 --- a/doc/tools/devtools.md +++ b/doc/tools/devtools.md @@ -5,7 +5,9 @@ to the browser devtools in order to inspect all owl apps that are present on any and allows to interract with their data to a certain extend. There is also a profiler available to visualize the components' lifecycle and be able to trace their origin. -## Install the extension +See the [`devtools doc`](devtools_guide.md) for more information. + +## Install the extension manually (for devs) In the owl root folder: diff --git a/doc/tools/devtools_guide.md b/doc/tools/devtools_guide.md new file mode 100644 index 00000000..9f589096 --- /dev/null +++ b/doc/tools/devtools_guide.md @@ -0,0 +1,150 @@ +# Owl Devtools Guide + +## Information popup + +After having installed the extension, a new icon will be added to your extension bar. +If you don't see it, you can pin the extension using the extensions popup. + + + +Clicking on the owl icon will open the information popup. This popup is useful +to know in advance whether owl is loaded in the tab or not. This is also indicated +by the icon itself: if it is flipped upside-down, it means that owl is not loaded in the +active tab. Do note that old versions of owl are not supported by the extension and will +therefore be indicated either as obsolete or absent by the extension popup. + + + +## First steps + +When you are on a page where owl is detected, you can open your devtools either with +right-click -> Inspect or using F12. In the devtools menu, you can search for the Owl +tab which is added by the extension. It will be present by default at the end of the list but +you can drag and drop it at the position you want for easier navigation in the future. + + + +When you open the tab, you arrive on the Components view by default which is one of the +two available tabs at the top. Here is an example of the devtools on the Odoo CRM app: + + + +## Components tab + +The components tab is separated into two sub windows: the components tree in the left and +the component details in the right. The components tree will display all the different +components that are present in the tab in the form of a tree. The root of this tree is +actually the app which is not a component but can still be inspected by the devtools like +one. There can also be multiple apps loaded in the page like in the following: + + + +There is a convenient search bar at the top of the components tree which will help finding +the components tou want in the tree and also, an element picker can be used to directly select +the component you want to focus on in the page which is especially useful when trying to find +what you want. Just click on the elements picker icon and click on the element you want to focus +on in the page and it will be selected in the devtools accordingly. Hovering any element in the +page in this mode will highlight it and the same happens anytime in the components tree. + + + +In the tree itself, the navigation is quite simple and is similar to the one in the Elements tab +of the browser's devtools. It is possible to navigate with the keyboard using the arrow keys and +multiple shortcuts are available in a custom menu when right-clicking on a component. This menu +allows to expand/fold all the children nodes of a component, fold its direct children only, inspect +the source code of the component, send it as a global variable in the console, go to the Elements tab +and focus on its content, force a rerender of the component, send its observed states to the console +as a global variable, inspect its compiled template in the Sources tab or send its raw template +to the console. + + + +The component details window in the right will show the component that is currently selected as well +as its env, props, observed states and all the other variables that are present on its instance. +While the props and the env are already present on the actual instance of the component and are +pretty explicit by themselves, the observed state value is a bit more complicated to grasp. + +The observed state is actually information about which variables are observed by the component +which will trigger a rerender of the component when it is modified. The keys represent which part of the +variable is actually observed and the target is the actual variable. For simplicity, the properties +that are not observed by the component are greyed out while the others are in bold. This means that +editing bold ones will trigger a rerender while the greyed out ones will not. + + + +In the given example, we have two keys/target pairs for two different variables. The first one indicates +that adding or removing an element to the array will trigger a rerender since the length will have changed. +Replacing the element at index 0, 1 or 2 will also have the same effect as implied by the keys. It doesn't +mean that editing the properties of element at index 0, 1 or 2 will rerender the component though. It may +be the case for some but this will be described in another keys/target pair. The second keys/target pair +is actually the element at index 0 of the first pair. It only has id in the keys meaning that only the +id property will actually trigger a rerender the component when modified. Be aware however that the other +properties may be in the observed state of another component like a child one in this case. A greyed out +property only implies it is not reactive for the selected component and not for the others. + +The navigation inside the properties is also similar to the one in console variables: properties have +their prototype displayed and getters will get their value when clicked on (...). It is also possible to +send any property to the console using the right-click context menu on it and functions can be inspected +in the sources tab as well. + + + +There are several icons available to perform several of the actions described before in the components +tree context menu and all these actions are also available by opening the menu by right-clicking on the +component's name. Using the left click on the component's name will focus it in the components tree. + +It is also possible to edit any of the leaf node properties. To do so, you must double click on the +property's value and modify it using the freshly created input then press enter to apply the changes. +Do note that the modified values should be written in JSON format in order to be valid (examples: +89, "yes", undefined, null, \["hello", 15\], {"a": 1}, true, ...). Whether it has an impact on the +component or not and whether it produces an error is the responsability of the user. + + + +## Profiler + +The profiler tab is the other tab of the owl devtools. It consists in an actions bar at the top and +a tree/list of events related to the owl components' renders. Here is an example of the events launched +when entering the Odoo Crm app. + + + +In the initial state, no event is displayed. You need to activate the recording of events before they +are intercepted by the devtools using the record button. + + + +The second button is used to clear all the events that have been recorded. The select can be used to +switch between the tree view (which shows the causality between renders) and the events log view which +simply displays the events in the exact order they were triggered. In this view, you can expand the create, +update and destroy events which reveals the component that initiated the event. + + + +The third button is only visible in tree view and allows to fold all the render events that were recorded. +Some actions are also available when using the right-click on any event of the tree view for navigation +purpose in a similar fashion as in the components tree. + + + +There is also the Trace Renderings and Trace Subscriptions features. These features are independant of the +recording of events and have no effect on the profiler tab. The Trace Renderings option is used to log in +the console all the render events and allows to show their traceback information. Similarly, the Trace +Subscriptions option logs all the properties that caused a render event and also allows to see the traceback +of the modification + + + + +## Options + +The owl devtools extension has a dark mode feature which defaults to your general devtools settings and can +be toggled using the sun/moon icon at the top-right corner of the tab. All the examples above were created +with the dark mode enabled. There is also a refresh button to completely reset the owl devtools. + + + +## Troubleshooting + +If the feedback from the page to the devtools seems to be cut, just close the devtools and refresh the page. +This will eventually happen any time a tab stays opened for too long without being refreshed. diff --git a/doc/tools/screenshots/crm.png b/doc/tools/screenshots/crm.png new file mode 100644 index 00000000..0db94650 Binary files /dev/null and b/doc/tools/screenshots/crm.png differ diff --git a/doc/tools/screenshots/darkmode.png b/doc/tools/screenshots/darkmode.png new file mode 100644 index 00000000..d6566861 Binary files /dev/null and b/doc/tools/screenshots/darkmode.png differ diff --git a/doc/tools/screenshots/edit.png b/doc/tools/screenshots/edit.png new file mode 100644 index 00000000..b025b49f Binary files /dev/null and b/doc/tools/screenshots/edit.png differ diff --git a/doc/tools/screenshots/events_log.png b/doc/tools/screenshots/events_log.png new file mode 100644 index 00000000..a59b9753 Binary files /dev/null and b/doc/tools/screenshots/events_log.png differ diff --git a/doc/tools/screenshots/extensions.png b/doc/tools/screenshots/extensions.png new file mode 100644 index 00000000..fafae436 Binary files /dev/null and b/doc/tools/screenshots/extensions.png differ diff --git a/doc/tools/screenshots/find_owl_tab.png b/doc/tools/screenshots/find_owl_tab.png new file mode 100644 index 00000000..fb46bfdd Binary files /dev/null and b/doc/tools/screenshots/find_owl_tab.png differ diff --git a/doc/tools/screenshots/function_menu.png b/doc/tools/screenshots/function_menu.png new file mode 100644 index 00000000..a2ec95fa Binary files /dev/null and b/doc/tools/screenshots/function_menu.png differ diff --git a/doc/tools/screenshots/menu.png b/doc/tools/screenshots/menu.png new file mode 100644 index 00000000..1b1ac761 Binary files /dev/null and b/doc/tools/screenshots/menu.png differ diff --git a/doc/tools/screenshots/multi_apps.png b/doc/tools/screenshots/multi_apps.png new file mode 100644 index 00000000..7b1645bd Binary files /dev/null and b/doc/tools/screenshots/multi_apps.png differ diff --git a/doc/tools/screenshots/picker.png b/doc/tools/screenshots/picker.png new file mode 100644 index 00000000..3b92516d Binary files /dev/null and b/doc/tools/screenshots/picker.png differ diff --git a/doc/tools/screenshots/popup.png b/doc/tools/screenshots/popup.png new file mode 100644 index 00000000..62e06efe Binary files /dev/null and b/doc/tools/screenshots/popup.png differ diff --git a/doc/tools/screenshots/profiler.png b/doc/tools/screenshots/profiler.png new file mode 100644 index 00000000..00c14b42 Binary files /dev/null and b/doc/tools/screenshots/profiler.png differ diff --git a/doc/tools/screenshots/record.png b/doc/tools/screenshots/record.png new file mode 100644 index 00000000..8bd7171c Binary files /dev/null and b/doc/tools/screenshots/record.png differ diff --git a/doc/tools/screenshots/states.png b/doc/tools/screenshots/states.png new file mode 100644 index 00000000..14ea4242 Binary files /dev/null and b/doc/tools/screenshots/states.png differ diff --git a/doc/tools/screenshots/trace_rendering.png b/doc/tools/screenshots/trace_rendering.png new file mode 100644 index 00000000..2a338470 Binary files /dev/null and b/doc/tools/screenshots/trace_rendering.png differ diff --git a/doc/tools/screenshots/trace_subscriptions.png b/doc/tools/screenshots/trace_subscriptions.png new file mode 100644 index 00000000..ba5788bd Binary files /dev/null and b/doc/tools/screenshots/trace_subscriptions.png differ diff --git a/doc/tools/screenshots/tree_actions.png b/doc/tools/screenshots/tree_actions.png new file mode 100644 index 00000000..33fc7b16 Binary files /dev/null and b/doc/tools/screenshots/tree_actions.png differ diff --git a/tests/tooling/doc_link_checker.test.ts b/tests/tooling/doc_link_checker.test.ts index 3fd63fc0..7764a80e 100644 --- a/tests/tooling/doc_link_checker.test.ts +++ b/tests/tooling/doc_link_checker.test.ts @@ -92,6 +92,10 @@ export function isLinkValid(link: MarkDownLink, current: FileData, files: FileDa // no check on external links return true; } + if (current.name.endsWith(".png")) { + // no check on png files + return true; + } // Step 1: extract path, name, hash // path = ['doc', 'architecture] // name = 'rendering.md'