Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions docs/_include/rtd-preview-navigate.inc
Original file line number Diff line number Diff line change
@@ -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 <https://app.readthedocs.org/projects/icalendar/builds/>`_.
Click the appropriate pull request and view its documentation.
- Under the list of CI checks, click the link :guilabel:`docs/readthedocs.org:icalendar`.
11 changes: 9 additions & 2 deletions docs/contribute/documentation/build-check.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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 <https://app.readthedocs.org/projects/icalendar/builds/>`_.
Use this feature to:

- :ref:`Check the change log entry <check-change-log>` 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 <https://docs.readthedocs.com/platform/stable/visual-diff.html>`_ 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.

Expand Down
6 changes: 2 additions & 4 deletions docs/contribute/documentation/style-guide.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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 <https://docs.readthedocs.com/platform/stable/visual-diff.html>`_ 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 <https://app.readthedocs.org/projects/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.
Expand Down
20 changes: 14 additions & 6 deletions docs/contribute/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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 <https://docs.readthedocs.com/platform/stable/visual-diff.html>`_ 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`.

Expand All @@ -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 <https://docs.readthedocs.com/platform/stable/visual-diff.html>`_ feature might help find what you've changed.


Set up for development
----------------------
Expand Down
1 change: 1 addition & 0 deletions news/2067.documentation
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Updated documentation of usage of Read the Docs pull request preview and visual diff features. @stevepiercy
Loading