Preview docs as part of PR

[stefmolin]

As part of the GitHub Actions workflows that run when a PR is opened, I'd like to have something like Matplotlib has that makes it possible to preview the built docs without downloading an artifact or building the docs locally.

Numpydoc also has this:

The details link goes to a preview hosted on CircleCI, but maybe a GitHub-only solution is possible with the latest changes in the artifact action, and using this action to set the details URL?

~Read the docs PR previews could also be an option.~

---

Edit: For numpydoc, we use an action to build the docs with CircleCI and then this action to generate that clickable link. This seems like the most promising option.

[sesdaile]

As far as I can tell the only method that will work is Read the docs PR previews as you suggested.

Things tried

• The upload-artifacts method results in all files being uploaded as a zip and thus can't be viewed via the browser. Not even a proxy such as htmlviewer will be able to work around this.
• Copying into the repo wiki will only work if using simple interpreted formats such as Markdown, MediaWiki, RDoc, Textile, or reStructuredText. Pushing html files simply does not work.
• Comments can contain simple html such as detail tags and horizontal rules but divs, spans, and other such things will not work, not to mention the issue with multiple pages.
• Deploying to a sub-folder of gh-pages the same way versioning works. This would create a security issue permitting anyone to deploy anything they want.

Read the Docs Config

Adding this config does nothing on it's own as the site needs to be configured via the Sign Up page. Instructions can be found here.

# .readthedocs.yaml
# Read the Docs configuration file for Sphinx projects
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

# Required
version: 2

# Set the OS, Python version and other tools you might need
build:
  os: ubuntu-22.04
  tools:
    python: "3"

sphinx:
  configuration: docs/conf.py

python:
  install:
    - method: pip
      path: .
      extra_requirements:
        - docs