From 450a36c91f5f97681b599e958f5a8333f18156d3 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 16 Nov 2026 23:25:25 -0800 Subject: [PATCH 1/2] Updated documentation of usage of Read the Docs pull request preview and visual diff features --- docs/_include/rtd-preview-navigate.inc | 5 +++++ docs/contribute/documentation/build-check.rst | 11 ++++++++-- docs/contribute/index.rst | 20 +++++++++++++------ news/2067.documentation | 1 + 4 files changed, 29 insertions(+), 8 deletions(-) create mode 100644 docs/_include/rtd-preview-navigate.inc create mode 100644 news/2067.documentation diff --git a/docs/_include/rtd-preview-navigate.inc b/docs/_include/rtd-preview-navigate.inc new file mode 100644 index 000000000..7c76842ab --- /dev/null +++ b/docs/_include/rtd-preview-navigate.inc @@ -0,0 +1,5 @@ +After opening a pull request and the CI check :guilabel:`docs/readthedocs.org:icalendar` succeeds, navigate to view documentation changes by either of the following routes. + +- `View all builds of documentation on Read the Docs `_. + Click the appropriate pull request and view its documentation. +- Under the list of CI checks, click the link :guilabel:`docs/readthedocs.org:icalendar`. diff --git a/docs/contribute/documentation/build-check.rst b/docs/contribute/documentation/build-check.rst index f96f84f8b..58c51eb9b 100644 --- a/docs/contribute/documentation/build-check.rst +++ b/docs/contribute/documentation/build-check.rst @@ -275,13 +275,20 @@ Document a package After adding and configuring a package, it's important to inform other people what the feature does and how to use it. +.. _pull-request-previews: + Pull request previews --------------------- On every pull request, Read the Docs generates a pull request preview of the documentation. -It creates a new comment containing a link to the preview in the pull request. -`View all builds of documentation on Read the Docs `_. +Use this feature to: + +- :ref:`Check the change log entry ` when creating a pull request. +- Ensure documentation and docstrings render correctly, including cross-references to Python objects and documentation sections and chapters. +- With the `visual diff `_ feature enabled, navigate between only those files and sections you've changed, and compare the differences of those changes. + +.. include:: ../../_include/rtd-preview-navigate.inc This feature is configured in the file :file:`.readthedocs.yml` and the repository settings. diff --git a/docs/contribute/index.rst b/docs/contribute/index.rst index 9b6679501..367a21168 100644 --- a/docs/contribute/index.rst +++ b/docs/contribute/index.rst @@ -322,12 +322,6 @@ Write a good change log entry with the following guidance. You should not write *how* you fixed it. - If you add or change a feature or public API, write a summary of previous behavior, what it does now, and how to use it. - Refer to narrative documentation as needed. -- After opening a pull request and the CI check :guilabel:`docs/readthedocs.org:icalendar` succeeds, inspect the rendered change log for accuracy and functional links. - - - Click the link :guilabel:`docs/readthedocs.org:icalendar` in the list of CI checks. - - Navigate to :menuselection:`Reference guides --> Change log`. - - Look for your rendered change log entry and inspect it. - Read the Docs' `visual diff `_ feature might help find what you've changed. The following text is an example of a good change log entry, placed inside :file:`/news/1360.feature`. @@ -341,6 +335,20 @@ The following would be a poor change log entry. Fix #123456 by chaning config of file [did_not_read_this_guide] +.. _check-change-log: + +Check change log +```````````````` + +.. include:: ../_include/rtd-preview-navigate.inc + +Once you're in the pull request preview: + +- Navigate to :menuselection:`Reference guides --> Change log`. +- Search for your username for the rendered change log entry, and inspect it for accuracy and functional links. + +Read the Docs' `visual diff `_ feature might help find what you've changed. + Set up for development ---------------------- diff --git a/news/2067.documentation b/news/2067.documentation new file mode 100644 index 000000000..edbbbb2f7 --- /dev/null +++ b/news/2067.documentation @@ -0,0 +1 @@ +Updated documentation of usage of Read the Docs pull request preview and visual diff features. @stevepiercy From 252408ad66229a4059fb8613102e7de8e4c98b71 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 16 Nov 2026 23:25:49 -0800 Subject: [PATCH 2/2] Updated documentation of usage of Read the Docs pull request preview and visual diff features --- docs/contribute/documentation/style-guide.rst | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/contribute/documentation/style-guide.rst b/docs/contribute/documentation/style-guide.rst index 2e5098c84..e84c965c7 100644 --- a/docs/contribute/documentation/style-guide.rst +++ b/docs/contribute/documentation/style-guide.rst @@ -438,11 +438,9 @@ When making a contribution to documentation, style and quality checks must pass See :doc:`build-check` for how to set up and run the builds and checks on documentation. In addition to automated checks, perform visual checks to ensure that documentation renders as intended. +Read the Docs' `visual diff `_ feature might help find what you've changed. -icalendar is configured with Read the Docs to build pull request previews of documentation. -When a pull request is opened on a branch and there are changes to any documentation files, Read the Docs will build a preview of the documentation, and insert a link to the build in the pull request description. -If there's no link, either there are no changes to documentation files or the branch isn't in the icalendar repository. -All pull request preview builds are listed on Read the Docs at `icalendar builds `_. +.. include:: ../../_include/rtd-preview-navigate.inc Always pay attention to errors and continuous integration failures, and attempt to resolve them. Warnings may provide helpful information.