I created the repository with readthedocs-preview, but that means that it is used as:

steps:
  - uses: readthedocs/readthedocs-preview@main

which repeats readthedocs. It is worth renaming it to something like:

• preview-url
• preview-links
• documentation-links
• pr-preview-links
• ....

This is the content of the PR description.

:books: Documentation preview :books:: https://another-slug--1.org.readthedocs.build/en/1/

:books: Documentation preview :books:: https://readthedocs-preview--1.org.readthedocs.build/en/1/

Extra content after the injected one. It should be intact after running it.

Multiple times now, I've surprised myself and tried to click the check for the PR docs links action in the PR list of checks. Apparently I'm confused by how prominent the check looks, but of course the "details" link for that check does not do what you expect.

I'm actually not even sure where this name comes from, but just assuming its centrally configured here somehow.

So, I would say this first check is more prominent that our own RTD build check:

And even though our check has our icon in that list, I still somehow want to click the first check, the check for the links. So, if I am actively/subconsciously doing this as someone familiar with RTD, there must be others that would notice this.

Looking more at this, "Read the Docs" looks more official than "docs/readthedocs.com:...", and the first link mentions "pull request preview". Though the links are in the PR description, users are probably still used to clicking the check detail links, so would be bound to hit this confusion.

This is a case where showing this action in the PR action list is probably a worse scenario, but that's up to GitHub to deal with.

But because we shouldn't expect users to interact with this particular action in the list of checks, I think a much less prominent name would at least not overwhelm our actual PR check.

We could follow the naming scheme used in other checks, this is definitely less prominent and doesn't make me want to keep clicking it.

I just tried this out for the first time here:

• https://github.com/simonw/sqlite-utils/pull/460

The preview link it added didn't work, maybe because I have a custom domain setup?

It linked to: https://readthedocs-preview--460.org.readthedocs.build/en/460/ - which 404s

Here's the correct link: https://sqlite-utils--460.org.readthedocs.build/en/460/

My docs are hosted at https://sqlite-utils.datasette.io/ using a custom subdomain setup like this: https://til.simonwillison.net/readthedocs/custom-subdomain

This is the case of our own repo https://github.com/readthedocs/readthedocs.org, where we have the docs and dev projects.

Currently, using the action more than once will override the previous comment

https://github.com/readthedocs/readthedocs-preview/blob/1029696f6a69477ff98e50ddb239e649f86ec384/action.yaml#L51

We should make the comment easier to locate, instead of using a plain ---- as separator, we could use a comment as a delimiter of the start/end of the comment. For example:

<!-- rtd-preview {project} start -->
Content
<!-- rtd-preview {project} end -->

That way, the current "separator" would be part of the template itself

---
:books: Documentation preview :books:: {docs-pr-index-url}

Currently, the action only supports "Read the Docs Community". To support "Read for Business" we will need to think about:

• the combination of the project's slug + organization's slug
• the hard coded org.readthedocs.build domain

Reference: https://github.com/readthedocs/readthedocs.org/pull/9450#discussion_r929260239

Fixes https://github.com/readthedocs/actions/issues/14

:books: Documentation preview :books:: https://readthedocs-preview--16.org.readthedocs.build/en/16/

This should probably be hitting our API to get an unresolved URL for the project, but for now, an option that is single_version or similar would be good. It's breaking the links in the WTD builds because we have a single_version there.

Currently we are installing it from main, but that means that it could be breaking changes. We should tag v1, so people can start using it at this simple state without worrying about us changing the behavior.

It would be good to detect changes under certain directories (e.g. docs/) and only update the description in that situation. Example of a potential input for the action:

file-path:
  description: "Path where to check for file modifications"
  default: "docs/"
  required: false

Note we could use github.rest.pulls.listFiles to get the files changed in the PR:

const {data: pull_files } = await github.rest.pulls.listFiles({
    owner: context.repo.owner,
    repo: context.repo.repo,
    pull_number: context.issue.number,
});

for (let file of pull_files) {
    // do something here
}

Add this as a comment so people can see it and adapt to their needs.

:books: Documentation preview :books:: https://readthedocs-preview--15.org.readthedocs.build/en/15/

After merging #16 and releasing a new v1 in #17; it would be good to publish this action in the GitHub Marketplace so people can find it easily. I don't have experience about how it works, but it would be good to research a little.

https://docs.github.com/en/actions/creating-actions/publishing-actions-in-github-marketplace

Merging #16 will make us to do a release of the v1 again. We want to follow what we talked at https://github.com/readthedocs/actions/issues/5#issuecomment-1197688541

This basically means re-tagging v1 to point to the latest commit that includes the single-version option.

Since this release process is no the common for other repositories, we need to document it in a clear way, so it's easy to follow.

The action currently edits the PR description to add a separator and below that the links.

It would be good if we can also support adding a new comment the first time and after that update the comment with the newer links, if any. Then, the user could choose the approach that like the most.

Both approaches have pros/cons that is worth considering.

We could detect there were changes to specific files (via #3) and insert direct links to those documentation pages as well. For example, if the file docs/page/section.rst was modified, we could insert the link https://readthedocs-preview--1.org.readthedocs.build/en/1/pages/section.html

There are some notes to mention:

• we need to know where is the root directory that matches the root of the URL (in this case, we need to remove docs/ from the filename)
• the URL is a pretty URL (/pages/section/ or /pages/section.html)
• support user-configurable amount of links (with a small default), to avoid flooding in case of many files changed