Add Web Inspector docs (WIP) #58

jdatapple · 2023-08-11T22:23:25Z

Ported Web Inspector docs from trac.webkit.org

docs/Deep Dive/Web Inspector/
docs/Deep Dive/Web Inspector/AnIntroduction.md
docs/Deep Dive/Web Inspector/Contributing.md
docs/Deep Dive/Web Inspector/RemoteInspectorWebKitGTKandWPE.md
docs/Deep Dive/Web Inspector/WebInspectorCodeStyle.md
docs/Deep Dive/Web Inspector/WebInspectorDebugging.md
docs/Deep Dive/Web Inspector/WebInspectorTests.md
docs/Deep Dive/Web Inspector/WebReplayMechanics.md

stwrt

Minor stylistic comments, but I don't have anything that is blocking.

Really appreciate you taking the time to port this over.

stwrt · 2023-08-12T01:24:30Z

docs/Deep Dive/Web Inspector/AnIntroduction.md

+
+### Remote Web Inspector on GTK+ and EFL ports
+
+ * For the GTK and EFL ports, this can be enabled with an environment variable. Check the documentation on EnvironmentVariables


Minor quip extra space

stwrt · 2023-08-12T01:24:57Z

docs/Deep Dive/Web Inspector/AnIntroduction.md

+Computer2 # MiniBrowser http://${ip.ad.dre.ss}:${port}
+```
+
+  * The very same version of WebKit has to be used on the other side


stwrt · 2023-08-12T01:26:19Z

docs/Deep Dive/Web Inspector/Contributing.md

+By inspecting the CSS property names in the second-level inspector, we quickly find that the colors are defined by rules in `Source/WebInspectorUI/UserInterface/Views/SpreadsheetCSSStyleDeclarationEditor.css`. 
+To create and submit a patch with our changes, we must to create an accompanying Bugzilla bug, and compute the diff of our changes against WebKit trunk.
+
+## Create / Update a Bug Report


I think we already have the content on how to build WebKit elsewhere, but this is not a big deal.

stwrt · 2023-08-12T01:26:37Z

docs/Deep Dive/Web Inspector/Contributing.md

+
+ 4. Edit `Source/WebInspectorUI/UserInterface/Views/SpreadsheetCSSStyleDeclarationEditor.css` within the repo.
+
+ 5. Run `make -C Source/WebInspectorUI release` to copy files from `Source/WebInspectorUI/UserInterface` to the build directory. Do it after every time you modify Inspector's files.


This is super helpful though. We should keep this.

stwrt · 2023-08-12T01:28:09Z

docs/Deep Dive/Web Inspector/WebReplayMechanics.md

@@ -0,0 +1,252 @@
+# Web Replay Mechanics
+
+*Brian Burg <burg@cs.washington.edu>*


This looks a little strange just having the name at the top here.

stwrt · 2023-08-12T01:29:55Z

docs/Deep Dive/Web Inspector/Contributing.md

+
+## Create / Update a Bug Report
+
+ * [Existing Web Inspector Bugs](https://bugs.webkit.org/buglist.cgi?query_format=advanced&short_desc_type=allwordssubstr&short_desc=&component=Web+Inspector&long_desc_type=substring&long_desc=&bug_file_loc_type=allwordssubstr&bug_file_loc=&keywords_type=allwords&keywords=&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&emailassigned_to1=1&emailtype1=substring&email1=&emailassigned_to2=1&emailreporter2=1&emailcc2=1&emailtype2=substring&email2=&bugidtype=include&bug_id=&votes=&chfieldfrom=&chfieldto=Now&chfieldvalue=&cmdtype=doit&order=Reuse+same+sort+as+last+time&field0-0-0=noop&type0-0-0=noop&value0-0-0=)


Extra space

mirnovov · 2023-08-12T04:41:54Z

docs/Deep Dive/Web Inspector/AnIntroduction.md

+
+Various HTML and JavaScript properties, including length of text nodes, offsetWidth/Height, class names, and parent/sibling information are vieweable in the Properties pane.
+
+See [Safari User Guide for Web Developers](http://developer.apple.com/safari/library/documentation/AppleApplications/Conceptual/Safari_Developer_Guide/UsingtheWebInspector/UsingtheWebInspector.html) for more details on other panels of the Web Inspector.


This link is out of date and leads to a 404. The most up to date WI documentation is at https://webkit.org/web-inspector/ afaik.

There's a overview of Web Inspector at:
https://developer.apple.com/documentation/safari-developer-tools/web-inspector
It's helpful to mention because its sibling pages detail how to inspect various types of targets (Simulators, remote devices, etc)

But I agree, we should point to the Web Inspector Reference at:
https://webkit.org/web-inspector/

stwrt · 2023-08-21T03:54:39Z

docs/Deep Dive/Web Inspector/AnIntroduction.md

+
+### Apple Web Inspector Remote Experiment
+
+[Safari User Guide for Web Developers](http://developer.apple.com/safari/library/documentation/AppleApplications/Conceptual/Safari_Developer_Guide/UsingtheWebInspector/UsingtheWebInspector.html)


Link does not work

I think we can remove the link altogether and keep the other two paragraphs for historical reference.

-[Safari User Guide for Web Developers](http://developer.apple.com/safari/library/documentation/AppleApplications/Conceptual/Safari_Developer_Guide/UsingtheWebInspector/UsingtheWebInspector.html)

stwrt · 2023-08-21T03:55:33Z

docs/Deep Dive/Web Inspector/WebInspectorCodeStyle.md

+
+### z-index
+
+Z-index variables are defined in [Variables.css](https://trac.webkit.org/browser/trunk/Source/WebInspectorUI/UserInterface/Views/Variables.css). Usage example:


Should update this to GitHub link

mirnovov · 2023-08-25T08:59:36Z

docs/Deep Dive/Web Inspector/Contributing.md

+For the Mac port, set the following defaults to allow inspecting the inspector.
+
+```
+defaults write NSGlobalDomain WebKitDebugDeveloperExtrasEnabled -bool YES


IDK if this still works but this can now be done from the web inspector UI.

That's correct. Developers can now enable "Allow Inspecting Web Inspector" in the Web Inspector Settings > Experimental tab.

I don't know if the defaults pref is relevant for other ports. I suspect not.

mirnovov · 2023-08-25T09:03:37Z

docs/Deep Dive/Web Inspector/AnIntroduction.md

+
+Under the Style pane we show all the CSS rules that apply to the focused node. These rules are listed in cascade order with overridden properties striked-out—letting you truly see how cascading stylesheets affect the page layout. All shorthand properties have a disclosure-triangle to show and hide the expanded properties created by the shorthand.
+
+The Metrics pane provides a quick visual look at how margins, borders and padding affect the current node.


Metrics are now under the Computed pane. Personally, I would just remove all this info and link to the documentation as a single source of truth to avoid it getting outdated again, but I’m a new contributor so those are just my thoughts.

I tend to agree. A paragraph or two about the general scope of Web Inspector is sufficient, then a add a link to the canonical Web Inspector Reference: https://webkit.org/web-inspector/

I would add a question mark in the help links, as it may not be obvious for people unfamiliar with Web Inspector.

"help links with a question mark"

mirnovov · 2023-08-25T09:06:06Z

docs/Deep Dive/Web Inspector/WebInspectorCodeStyle.md

@@ -0,0 +1,281 @@
+# Web Inspector Syle Guide


stwrt · 2023-08-25T15:09:18Z

docs/Deep Dive/Web Inspector/AnIntroduction.md

+
+|                             | Mac | Windows / Linux |
+|-----------------------------|-----|-----------------|
+| Next Panel                  | ⌘]  | Ctrl-]          |


This should be ⌘} and ``⌘{`.

This information is quite similar to here.
https://webkit.org/web-inspector/keyboard-shortcuts/

rcaliman-apple · 2023-09-29T13:17:38Z

docs/Deep Dive/Web Inspector/WebReplayMechanics.md

Web Replay was removed from WebKit at some point. There's the meta bug for adding it, but I can't find the definitive bug which removed it. Perhaps @burg can point to it.

This documentation file should be archived.

rcaliman-apple · 2023-09-29T13:21:45Z

docs/Deep Dive/Web Inspector/AnIntroduction.md

+
+### Safari
+
+* Enable the Develop menu option in the Advanced preferences.


- Enable the Develop menu option in the Advanced preferences. + Enable ["Show features for web developers"](https://developer.apple.com/documentation/safari-developer-tools/enabling-developer-features) in the Advanced tab of Safari settings.

rcaliman-apple · 2023-09-29T13:31:05Z

docs/Deep Dive/Web Inspector/AnIntroduction.md

+
+### Apple Web Inspector Remote Experiment
+
+[Safari User Guide for Web Developers](http://developer.apple.com/safari/library/documentation/AppleApplications/Conceptual/Safari_Developer_Guide/UsingtheWebInspector/UsingtheWebInspector.html)


I think we can remove the link altogether and keep the other two paragraphs for historical reference.

-[Safari User Guide for Web Developers](http://developer.apple.com/safari/library/documentation/AppleApplications/Conceptual/Safari_Developer_Guide/UsingtheWebInspector/UsingtheWebInspector.html)

rcaliman-apple · 2023-09-29T13:39:39Z

docs/Deep Dive/Web Inspector/AnIntroduction.md

+
+Various HTML and JavaScript properties, including length of text nodes, offsetWidth/Height, class names, and parent/sibling information are vieweable in the Properties pane.
+
+See [Safari User Guide for Web Developers](http://developer.apple.com/safari/library/documentation/AppleApplications/Conceptual/Safari_Developer_Guide/UsingtheWebInspector/UsingtheWebInspector.html) for more details on other panels of the Web Inspector.


There's a overview of Web Inspector at:
https://developer.apple.com/documentation/safari-developer-tools/web-inspector
It's helpful to mention because its sibling pages detail how to inspect various types of targets (Simulators, remote devices, etc)

But I agree, we should point to the Web Inspector Reference at:
https://webkit.org/web-inspector/

rcaliman-apple · 2023-09-29T13:40:22Z

docs/Deep Dive/Web Inspector/AnIntroduction.md

+
+Under the Style pane we show all the CSS rules that apply to the focused node. These rules are listed in cascade order with overridden properties striked-out—letting you truly see how cascading stylesheets affect the page layout. All shorthand properties have a disclosure-triangle to show and hide the expanded properties created by the shorthand.
+
+The Metrics pane provides a quick visual look at how margins, borders and padding affect the current node.


I tend to agree. A paragraph or two about the general scope of Web Inspector is sufficient, then a add a link to the canonical Web Inspector Reference: https://webkit.org/web-inspector/

rcaliman-apple · 2023-09-29T14:10:55Z

docs/Deep Dive/Web Inspector/Contributing.md

+For the Mac port, set the following defaults to allow inspecting the inspector.
+
+```
+defaults write NSGlobalDomain WebKitDebugDeveloperExtrasEnabled -bool YES


That's correct. Developers can now enable "Allow Inspecting Web Inspector" in the Web Inspector Settings > Experimental tab.

I don't know if the defaults pref is relevant for other ports. I suspect not.

rcaliman-apple · 2023-09-29T14:40:22Z

docs/Deep Dive/Web Inspector/WebInspectorTests.md

+
+## How to Debug Tests
+
+In general, the strategies for [wiki:"WebInspectorDebugging" debugging the Web Inspector] and debugging WebCore/WebKit2 apply the same to debugging inspector tests. Sometimes, tests can be more difficult to debug because the test harness' marshalling code can be broken by incorrectly written tests or bugs in the test harness. The test stubs provide several flags that enable extra or more reliable logging for debug purposes. Flags can be set in the corresponding `Test/TestStub.html` file for all test runs, or at the top of a `test()` method to only affect one test.


[wiki:"WebInspectorDebugging" debugging the Web Inspector]
Needs updated link referencing the WebInspectorDebugging.md file from this patch.

stwrt · 2024-02-07T20:56:17Z

Not sure why it is suddenly showing 20 commits. Maybe you need to rebase?

rcaliman-apple · 2024-02-07T20:58:08Z

Not sure why it is suddenly showing 20 commits. Maybe you need to rebase?

I did. But I guess I messed up elsewhere with my git commands.

I'll likely send it another PR. Sorry about the noise! 😞

Ported Web Inspector docs from trac.webkit.org

4644cb7

jdatapple assigned jdatapple and rcaliman-apple Aug 11, 2023

stwrt reviewed Aug 12, 2023

View reviewed changes

mirnovov reviewed Aug 12, 2023

View reviewed changes

stwrt reviewed Aug 21, 2023

View reviewed changes

mirnovov reviewed Aug 25, 2023

View reviewed changes

stwrt reviewed Aug 25, 2023

View reviewed changes

stwrt requested a review from rcaliman-apple September 22, 2023 01:40

rcaliman-apple reviewed Sep 29, 2023

View reviewed changes

rcaliman-apple force-pushed the draft/web-inspector branch from 3f20dda to 5f5eef1 Compare February 7, 2024 20:47

rcaliman-apple force-pushed the draft/web-inspector branch from 3f20dda to 4644cb7 Compare February 12, 2024 19:12

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add Web Inspector docs (WIP) #58

Add Web Inspector docs (WIP) #58

jdatapple commented Aug 11, 2023

stwrt left a comment

stwrt Aug 12, 2023

stwrt Aug 12, 2023

stwrt Aug 12, 2023

stwrt Aug 12, 2023

stwrt Aug 12, 2023

stwrt Aug 12, 2023

mirnovov Aug 12, 2023

rcaliman-apple Sep 29, 2023

stwrt Aug 21, 2023

rcaliman-apple Sep 29, 2023

stwrt Aug 21, 2023

mirnovov Aug 25, 2023

rcaliman-apple Sep 29, 2023

mirnovov Aug 25, 2023

rcaliman-apple Sep 29, 2023

celestaria Feb 7, 2024

mirnovov Aug 25, 2023

stwrt Aug 25, 2023

rcaliman-apple Sep 29, 2023

rcaliman-apple Sep 29, 2023

rcaliman-apple Sep 29, 2023

rcaliman-apple Sep 29, 2023

rcaliman-apple Sep 29, 2023

rcaliman-apple Sep 29, 2023

rcaliman-apple Sep 29, 2023

stwrt commented Feb 7, 2024

rcaliman-apple commented Feb 7, 2024


		### Remote Web Inspector on GTK+ and EFL ports

		* For the GTK and EFL ports, this can be enabled with an environment variable. Check the documentation on EnvironmentVariables


		4. Edit `Source/WebInspectorUI/UserInterface/Views/SpreadsheetCSSStyleDeclarationEditor.css` within the repo.

		5. Run `make -C Source/WebInspectorUI release` to copy files from `Source/WebInspectorUI/UserInterface` to the build directory. Do it after every time you modify Inspector's files.

		@@ -0,0 +1,252 @@
		# Web Replay Mechanics

		Brian Burg <burg@cs.washington.edu>


		## Create / Update a Bug Report

		* [Existing Web Inspector Bugs](https://bugs.webkit.org/buglist.cgi?query_format=advanced&short_desc_type=allwordssubstr&short_desc=&component=Web+Inspector&long_desc_type=substring&long_desc=&bug_file_loc_type=allwordssubstr&bug_file_loc=&keywords_type=allwords&keywords=&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&emailassigned_to1=1&emailtype1=substring&email1=&emailassigned_to2=1&emailreporter2=1&emailcc2=1&emailtype2=substring&email2=&bugidtype=include&bug_id=&votes=&chfieldfrom=&chfieldto=Now&chfieldvalue=&cmdtype=doit&order=Reuse+same+sort+as+last+time&field0-0-0=noop&type0-0-0=noop&value0-0-0=)


		Various HTML and JavaScript properties, including length of text nodes, offsetWidth/Height, class names, and parent/sibling information are vieweable in the Properties pane.

		See [Safari User Guide for Web Developers](http://developer.apple.com/safari/library/documentation/AppleApplications/Conceptual/Safari_Developer_Guide/UsingtheWebInspector/UsingtheWebInspector.html) for more details on other panels of the Web Inspector.


		### Apple Web Inspector Remote Experiment

		[Safari User Guide for Web Developers](http://developer.apple.com/safari/library/documentation/AppleApplications/Conceptual/Safari_Developer_Guide/UsingtheWebInspector/UsingtheWebInspector.html)


		### z-index

		Z-index variables are defined in [Variables.css](https://trac.webkit.org/browser/trunk/Source/WebInspectorUI/UserInterface/Views/Variables.css). Usage example:


		Under the Style pane we show all the CSS rules that apply to the focused node. These rules are listed in cascade order with overridden properties striked-out—letting you truly see how cascading stylesheets affect the page layout. All shorthand properties have a disclosure-triangle to show and hide the expanded properties created by the shorthand.

		The Metrics pane provides a quick visual look at how margins, borders and padding affect the current node.


		### Safari

		* Enable the Develop menu option in the Advanced preferences.


		## How to Debug Tests

		In general, the strategies for [wiki:"WebInspectorDebugging" debugging the Web Inspector] and debugging WebCore/WebKit2 apply the same to debugging inspector tests. Sometimes, tests can be more difficult to debug because the test harness' marshalling code can be broken by incorrectly written tests or bugs in the test harness. The test stubs provide several flags that enable extra or more reliable logging for debug purposes. Flags can be set in the corresponding `Test/TestStub.html` file for all test runs, or at the top of a `test()` method to only affect one test.

Add Web Inspector docs (WIP) #58

Are you sure you want to change the base?

Add Web Inspector docs (WIP) #58

Conversation

jdatapple commented Aug 11, 2023

stwrt left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

stwrt commented Feb 7, 2024

rcaliman-apple commented Feb 7, 2024