DevTools guide (#16)

* feat: devtools guide * One sentence per line * Style and orthography * Sometimes a window opens for accepting incoming connections * Expand overview of Inspector tab * Gerund heading for consistency with other heading * Clarify port parameter --------- Co-authored-by: Delan Azabani <[email protected]>
servo · Aug 26, 2024 · 3e53645 · 3e53645
1 parent 1fa8920
commit 3e53645
Show file tree

Hide file tree

Showing 8 changed files with 72 additions and 6 deletions.
diff --git a/src/SUMMARY.md b/src/SUMMARY.md
@@ -19,6 +19,7 @@
   - [Working on a crate\*](hacking/working-on-a-crate.md)
 - [Editor support](hacking/editor-support.md)
 - [Debugging](hacking/debugging.md)
+  - [Using DevTools](hacking/using-devtools.md)
 - [Automated testing\*](hacking/testing.md)
 - [Profiling\*](hacking/profiling.md)
 - [Diagnosing bugs in real websites](hacking/web-compat-bugs.md)

diff --git a/src/hacking/using-devtools.md b/src/hacking/using-devtools.md
@@ -0,0 +1,65 @@
+# DevTools
+
+[Firefox DevTools](https://firefox-source-docs.mozilla.org/devtools-user) are a set of web developer tools that can be used to examine, edit, and debug a website's HTML, CSS, and JavaScript.
+Servo has support for a subset of DevTools functionality, allowing for simple debugging.
+
+## Connecting to Servo
+
+1. Run servoshell with the DevTools server enabled.
+   The number after the `devtools` parameter is the port used by the server.
+
+```sh
+./mach run --devtools=6080
+```
+
+2. Open Firefox and go to `about:debugging`.
+   If this is your first time using the DevTools integration, go to **Setup** and add `localhost:6080` as a [network location](https://firefox-source-docs.mozilla.org/devtools-user/about_colon_debugging/index.html#connecting-over-the-network).
+   The port number must be the same as in the previous step.
+
+3. Click on **Connect** in the sidebar next to `localhost:6080`.
+
+![Setting up the port in Firefox](../images/devtools-firefox-setup.png)
+
+4. Accept the incoming connection.
+   If no confirmation dialog appears, press `Y` in the terminal that servoshell is running in.
+
+![Accept the connection in the terminal](../images/devtools-accept-connection.png)
+
+5. Back in Firefox, choose a webview and click **Inspect**.
+   A new window should open with the page's inspector.
+
+![Inspect a tab](../images/devtools-inspect-tab.png)
+
+## Using the inspector
+
+The inspector window is divided in various tabs with different workspaces.
+At the moment, **Inspector** and **Console** are working.
+
+In the **Inspector** tab there are three columns.
+From left to right:
+
+- The **HTML tree** shows the document nodes.
+  This allows you to see, add, or modify attributes by double-clicking on the tag name or attribute.
+- The **style inspector** displays the CSS styles associated with the selected element.
+  The entries here come from the element's style attribute, from matching stylesheet rules, or inherited from other elements.
+  Styles can be added or modified by clicking on a selector or property, or clicking in the empty space below.
+- The **extra column** contains more helpful tools:
+  - **Layout** contains information about the box model properties of the element.
+    Note that flex and grid do not work yet.
+  - **Computed**, which contains all of the CSS [computed values](https://drafts.csswg.org/css-cascade/#computed) after resolving things like relative units.
+
+![Inspector](../images/devtools-inspector.png)
+
+The **Console** tab contains a JavaScript console that interfaces with the website being displayed in Servo.
+Errors, warnings, and information that the website produces will be logged here.
+It can also be used to run JavaScript code directly on the website, for example, changing the document content or reloading the page:
+
+```js
+document.write("Hello, Servo!")
+location.reload()
+```
+
+<div class="warning">
+
+**Note:** support for DevTools features is still a work in progress, and it can break in future versions of Firefox if there are changes to the messaging protocol.
+</div>
diff --git a/src/images/devtools-accept-connection.png b/src/images/devtools-accept-connection.png
diff --git a/src/images/devtools-firefox-setup.png b/src/images/devtools-firefox-setup.png
diff --git a/src/images/devtools-inspect-tab.png b/src/images/devtools-inspect-tab.png
diff --git a/src/images/devtools-inspector.png b/src/images/devtools-inspector.png
diff --git a/src/running-servoshell.md b/src/running-servoshell.md
@@ -19,17 +19,12 @@ For example, to run our [Conway’s Game of Life demo](https://demo.servo.org/ex
 $ ./servo --pref dom.webgpu.enabled https://demo.servo.org/experiments/webgpu-game-of-life/
 ```
 
-Use `--devtools=6080` to enable support for [debugging pages with Firefox devtools](https://firefox-source-docs.mozilla.org/devtools-user/about_colon_debugging/index.html#connecting-over-the-network):
+Use `--devtools=6080` to enable support for [debugging pages with Firefox devtools](hacking/using-devtools.md):
 
 ```sh
 $ ./servo --devtools=6080
 ```
 
-<div class="warning">
-
-**Note:** devtools support is currently a work in progress ([#32404](https://github.com/servo/servo/issues/32404)).
-</div>
-
 ## Built servoshell yourself?
 
 When you build it yourself, servoshell will be in `target/debug/servo` or `target/release/servo`.

diff --git a/src/style-guide.md b/src/style-guide.md
@@ -12,6 +12,11 @@ Then to fix indentation of simple lists, you can replace `^([*-] .*\n([* -].*\n)
 
 - For consistency, indent nested lists with two spaces, and use `-` for unordered lists
 
+## Notation
+
+- Use **bold text** when referring to UI elements like menu options, e.g. “click **Inspect**”
+- Use `backticks` when referring to single-letter keyboard keys, e.g. “press `A` or Ctrl+`A`”
+
 ## Error messages
 
 - Where possible, always include a link to documentation, Zulip chat, or source code — this helps preserve the original context, and helps us check and update our advice over time