diff --git a/docs/user/visual-diff.rst b/docs/user/visual-diff.rst index 263511d0b5c..cfe2a741447 100644 --- a/docs/user/visual-diff.rst +++ b/docs/user/visual-diff.rst @@ -1,46 +1,72 @@ -Visual diff -=========== +Pull request diff +================= -Visual diff allows you to see a visual :term:`diff` on a documentation page, -showing what has changed between the ``latest`` version and the active :doc:`pull request `. +Get a list of documentation files that changed between the pull request and the latest version of the documentation, +and see their differences highlighted visually on the documentation pages. -Visual diff allows you to quickly review changes visually, -and focus your review on what has changed in the current page. +While it's helpful to see the changes in source files, +it can be difficult to understand how those changes will look in the rendered documentation, +or their impact in the documentation as a whole. +Read the Docs makes it easy to see the changes in the rendered documentation. -Using Visual diff ------------------ +.. figure:: /img/screenshot-viz-diff-ui.png + :width: 80% + +Configuration +------------- + +The following options are available: -Visual diff is enabled by default and is only available on pull request builds. -It works by comparing the current page with the default version of the documentation (e.g. where `/` redirects to). +Show diff menu in preview +~~~~~~~~~~~~~~~~~~~~~~~~~ -When Visual diff is enabled, -a new UI element appears at the top right of the page showing a dropdown selector containing all the files that have changed in that pull request build. +Addon (TBD) + +When enabnled, a new UI element appears at the top right of the page showing a dropdown selector containing all the files that have changed in that pull request build. .. figure:: /img/screenshot-viz-diff-ui.png :width: 80% You can select any of those files from the dropdown to jump directly into that page. -Once there, you can toggle Visual Diff on and off by pressing the :guilabel:`Show diff` link from the UI element, or pressing the `d` key if you have hotkeys enabled. +Once there, you can toggle visual diff on and off by pressing the :guilabel:`Show diff` link from the UI element, or pressing the `d` key if you have hotkeys enabled. Visual diff will show all the sections that have changed and their differences highlighted with red/green background colors. Then you can jump between each of these chunks by clinking on the up/down arrows. -Configuring Visual Diff ------------------------ +Show diff in the pull request +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +TBD + +Base version +~~~~~~~~~~~~ + +The base version is the version of the documentation that is used to compare against the pull request. +By default, this is the latest version of the documentation. -All the available configuration for the visual diff addon can be found under :guilabel:`Settings > Addons > Visual diff` in the :term:`dashboard`. -You can choose to disable/enable the `Visual diff` feature on a per project basis. -Visual diff can also ignore files by specifying these files under `File tree diff`, regex supported. +Ignore files +~~~~~~~~~~~~ -Troubleshooting Visual diff ---------------------------- +Patterns are matched against the relative paths of the HTML files produced by the build, +you should try to match ``index.html``, not ``docs/index.rst``, nor ``/en/latest/index.html``. +Patterns can include one or more of the following special characters: -Visual diff only works when we detect changes on the page, -so ensure you are on a page that has changed in the current pull request. +- ``*`` matches everything, including slashes. +- ``?`` matches any single character. +- ``[seq]`` matches any character in ``seq``. -There are also some known issues that currently don't display properly. -We are working to improve the UX, but so far we've found the following issues: +Limitations and known issues +---------------------------- -* **Tables** are shown to have changes when they may not have changed. This is due to subtle variations in how HTML tables are rendered, and will be fixed in a future version. -* **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. -* **Chunks background is incorrect** when we are unable to detect the correct main parent element for the chunk. +- Only HTML files are taken into consideration for the diff. +- The diff is done between the files from the latest successful build of the pull request and the default base version (latest by default). + If your pull request get's out of sync with the branch it is based on, the diff may not be accurate, and may show unrelated files an sections as changed. +- The diff is done by comparing the "main content" of the HTML files. + This means that some changes outside the main content, like header or footer, may not be detected. + This is done to avoid showing changes that are not relevant to the documentation content itself. + Like all pages being marked as changed because of a date or commmit hash being updated in the footer. +- Invisible changes. Some sections may be highlighted as changed, even when they haven't actually visually changed. + This can be due the underlying HTML changing, but there is no visual change, for example, if the URL of a link changed. +- Tables may be shown to have changes when they have not actually changed. + This is due to subtle variations in how HTML tables are rendered, and will be fixed in a future version. +- The background of diff chunks may be incorrect when we are unable to detect the correct main parent element for the chunk.