Skip to content

Commit cdd9597

Browse files
File Tree Diff: small documentation to mention the file selector (#12011)
Briefly explanation about how to use visual doc diff. Closes #12009 <!-- readthedocs-preview docs start --> --- :books: Documentation previews :books: - User's documentation (`docs`): https://docs--12011.org.readthedocs.build/en/12011/ <!-- readthedocs-preview docs end --> <!-- readthedocs-preview dev start --> - Developer's documentation (`dev`): https://dev--12011.org.readthedocs.build/en/12011/ <!-- readthedocs-preview dev end --> --------- Co-authored-by: Eric Holscher <25510+ericholscher@users.noreply.github.com>
1 parent 153e79f commit cdd9597

File tree

1 file changed

+18
-6
lines changed

1 file changed

+18
-6
lines changed

docs/user/visual-diff.rst

Lines changed: 18 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -12,18 +12,30 @@ and focus your review on what has changed in the current page.
1212

1313
Example of Visual diff
1414

15-
Enabling Visual diff
16-
--------------------
15+
Using Visual diff
16+
-----------------
17+
18+
Visual diff is enabled by default and it's only available on pull request builds.
19+
Once enabled, a new UI element appears at the top-right of the page showing a dropdown selector containing
20+
all the files that have changed between the base version (e.g. ``latest``) and the current pull request build.
21+
22+
You can select any of those files from the dropdown to jump directly into that page.
23+
Once there, you can toggle it on/off by pressing the :guilabel:`Show diff` link from the UI element, or pressing the `d` key if you have hotkeys enabled.
24+
Visual diff will show all the sections that have changed and their differences highlighted with red/green background colors.
25+
Then you can jump between each of these chunks by clinking on the up/down arrows.
26+
27+
All the available configuration for the visual diff addon can be found under :guilabel:`Settings > Addons > Visual diff` in the :term:`dashboard`.
1728

18-
Visual diff is only enabled on pull request builds,
19-
and can be toggled on and off with the ``d`` hotkey.
2029

2130
Troubleshooting Visual diff
2231
---------------------------
2332

24-
Visual diff only works if there are changes on the page,
33+
Visual diff only works when we detect changes on the page,
2534
so ensure you are on a page that has changed in the current pull request.
2635

27-
There are also some known issues that currently don't display properly:
36+
There are also some known issues that currently don't display properly.
37+
We are working to improve the UX, but so far we've found the following issues:
2838

2939
* **Tables** are shown to have changes when they may not have changed. This is due to do subtly in how HTML tables are rendered, and will be fixed in a future version.
40+
* **Invisible changes** sometimes are marked as diff due than the underlying HTML changing, but there is no visual change. This could happen if the URL of a link changed, for example.
41+
* **Chunks background is incorrect** when we are unable to detect the correct main parent element for the chunk.

0 commit comments

Comments
 (0)