From 081233357d4dbe0cabe890009d674839d9de18be Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Philipp=20Kr=C3=BCger?= <philipp.krueger1@gmail.com>
Date: Fri, 26 Jul 2024 15:09:18 +0200
Subject: [PATCH] ci: Generate docs for each PR (#2547)

## Description

<!-- A summary of what this pull request achieves and a rough list of
changes. -->

Added a `docs.yaml` workflow that makes the github action bot reply to
PRs with a link to built docs to your PRs.
It only does so once, and then just updates the comment (although
actually it doesn't necessarily need to, the link is always the same,
but it's still nice in case someone changes the workflow).

This is using the nightly toolchain, because we're using
[`#[feature(doc_cfg)]`](https://doc.rust-lang.org/unstable-book/language-features/doc-cfg.html).

## Motivation

I personally wanted this. Every now and then we get a PR with the
description saying "the best way to review this is to start by looking
at the generated docs". But then I need to checkout the PR, build the
docs and open them. Having a link directly to the docs would be
*amazing* IMO.

I *also* think that having easy access to docs on every PR will make
people check out the rendered docs on PRs more often. My hope here is
that doc quality will thus improve.

## Breaking Changes

<!-- Optional, if there are any breaking changes document them,
including how to migrate older code. -->

None of course. This is only CI.

## Notes & open questions

<!-- Any notes, remarks or open questions you have to make about the PR.
-->

Wdyt?

## Change checklist

- [x] Self-review.
- ~~[ ] Documentation updates following the [style
guide](https://rust-lang.github.io/rfcs/1574-more-api-documentation-conventions.html#appendix-a-full-conventions-text),
if relevant.~~
- ~~[ ] Tests if relevant.~~
- ~~[ ] All breaking changes documented.~~
---
 .github/workflows/docs.yaml | 56 +++++++++++++++++++++++++++++++++++++
 1 file changed, 56 insertions(+)
 create mode 100644 .github/workflows/docs.yaml

diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml
new file mode 100644
index 0000000000..d9b51ec44f
--- /dev/null
+++ b/.github/workflows/docs.yaml
@@ -0,0 +1,56 @@
+name: Docs Preview
+
+on:
+  pull_request:
+
+jobs:
+  preview_docs:
+    timeout-minutes: 30
+    name: Docs preview
+    if: "github.event_name == 'pull_request'"
+    runs-on: ubuntu-latest
+    env:
+      RUSTC_WRAPPER: "sccache"
+      SCCACHE_GHA_ENABLED: "on"
+      SCCACHE_CACHE_SIZE: "50G"
+      PREVIEW_PATH: pr/${{ github.event.pull_request.number }}/docs
+
+    steps:
+    - uses: actions/checkout@v4
+    - uses: dtolnay/rust-toolchain@master
+      with:
+        toolchain: nightly-2024-05-02
+    - name: Install sccache
+      uses: mozilla-actions/sccache-action@v0.0.5
+
+    - name: Generate Docs
+      run: cargo doc --workspace --all-features --no-deps
+      env:
+        RUSTDOCFLAGS: --cfg docsrs
+
+    - name: Deploy Docs to Preview Branch
+      uses: peaceiris/actions-gh-pages@v4
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: ./target/doc/
+        destination_dir: ${{ env.PREVIEW_PATH }}
+        publish_branch: generated-docs-preview
+
+    - name: Find Docs Comment
+      uses: peter-evans/find-comment@v3
+      id: fc
+      with:
+        issue-number: ${{ github.event.pull_request.number }}
+        comment-author: 'github-actions[bot]'
+        body-includes: Documentation for this PR has been generated
+
+    - name: Create or Update Docs Comment
+      uses: peter-evans/create-or-update-comment@v4
+      with:
+        issue-number: ${{ github.event.pull_request.number }}
+        comment-id: ${{ steps.fc.outputs.comment-id }}
+        body: |
+          Documentation for this PR has been generated and is available at: https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/${{ env.PREVIEW_PATH }}/iroh/
+          
+          Last updated: ${{ github.event.pull_request.updated_at }}
+        edit-mode: replace