Docs: update visual diff docs #12453
Conversation
Documentation build overview
Show files changed (5 files in total): 📝 5 modified | ➕ 0 added | ➖ 0 deleted
|
| Visual diff shows all the sections that have changed, highlighting their differences with red/green background colors. | ||
| You can jump between each of these chunks by clinking on the up/down arrows. | ||
|
|
||
| Show build overview in pull requests |
There was a problem hiding this comment.
We should definitely try to promote this more in marketing, because I think it's a great viral feature for non-users to learn about the value of RTD.
I wonder if we should default it on? Or have a prompt for users to turn it on or something?
There was a problem hiding this comment.
yeah, we could have a blog post too
|
|
||
| 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. | ||
| Ignored files |
There was a problem hiding this comment.
I forgot we implemented this! Super useful, and I will go change this on a few projects :)
|
|
||
| Configuring Visual Diff | ||
| ----------------------- | ||
| You can configure a list of files or patterns to be ignored when listing the files that changed in the pull request. |
There was a problem hiding this comment.
| You can configure a list of files or patterns to be ignored when listing the files that changed in the pull request. | |
| You can configure a list of files or patterns to be ignored when listing the files that changed in the pull request. | |
| This is useful when you have files that have a date in them, or listing/archive files that show changes without content changes in those files. |
docs/user/visual-diff.rst
Outdated
| ~~~~~~~~~~~~ | ||
|
|
||
| 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. |
There was a problem hiding this comment.
| By default, this is the latest version of the documentation. | |
| By default, this is the ``latest`` version of the documentation. |
What is the primary reason users would want this? If they didn't have a latest version enabled? We should mention a use case here.
There was a problem hiding this comment.
In case their main branch isn't pointed to latest.
| - 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 gets out of sync with its base branch, the diff may not be accurate, and may show unrelated files and sections as changed. |
There was a problem hiding this comment.
I'd really love to find a better way to handle this, as it's the #1 UX issue with it that I see regularly. Not sure how to really fix it tho, perhaps using git to see what files have changed between the base main 🤷
There was a problem hiding this comment.
I opened an issue about this some time ago #12232
Documentation build overview
Show files changed (6 files in total): 📝 6 modified | ➕ 0 added | ➖ 0 deleted
|
Extracted from #12276