Repository: AeneasVerif/charon
Pull request #611: feat: deploy index.html and rustc internal APIs to Github Pages
Author: login: zjp-CN
Created: 2025-03-17T06:57:49Z | Merged: 2025-03-17T14:45:24Z

close #610 

![20250317145708](https://github.com/user-attachments/assets/2b6fa7b1-5e7e-4647-9453-720f7a5e9700)


Preview: https://os-checker.github.io/charon

Linked issue #610: Add index.html and rustc internal API docs for Github Pages

Currently [aeneasverif.github.io/charon](https://aeneasverif.github.io/charon) is 404.

I can add an index.html file in deployment path to point to these pages:
* charon's API docs, i.e.  [aeneasverif.github.io/charon/charon_lib](https://aeneasverif.github.io/charon/charon_lib) introduceed in  https://github.com/AeneasVerif/charon/issues/445
* rustc internal API docs required by charon's toolchain


It'll look [like](https://os-checker.github.io/Rudra) this for modified Rudra, since I want to reference these APIs online when learning about the codebase.
Linked issue comments: user: login: Nadrieril
created_at: 2025-03-16T16:03:06Z
body: FWIW I use the [latest internal nightly docs](https://doc.rust-lang.org/nightly/nightly-rustc/) wne developing charon and they work pretty well. There sometimes are differences with charon's pinned rustc version but they tend to be minimal.

That said feel free to make a PR with what you suggest, seems good to me if that's helpful to you.
author_association: MEMBER

Diff:
diff --git a/.github/index.html b/.github/index.html
new file mode 100644
index 000000000..7d01003d4
--- /dev/null
+++ b/.github/index.html
@@ -0,0 +1,61 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>API Docs</title>
+  <style>
+    body {
+      font-family: Arial, sans-serif;
+      margin: 20px;
+      background-color: #f8f8f8;
+      color: #333;
+    }
+
+    h2 {
+      margin-bottom: 10px;
+      font-size: 1.5em;
+      color: #2c3e50;
+    }
+
+    ul {
+      list-style-type: none;
+      padding: 0;
+      margin: 0;
+    }
+
+    li {
+      margin-bottom: 15px;
+      padding: 10px;
+      background-color: #ffffff;
+      border: 1px solid #ddd;
+      border-radius: 5px;
+      box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
+    }
+
+    a {
+      text-decoration: none;
+      color: #3498db;
+      font-weight: bold;
+    }
+
+    a:hover {
+      text-decoration: underline;
+    }
+  </style>
+</head>
+
+<body>
+  <h2>Charon related API docs</h2>
+  <ul>
+    <li>
+      <a href="./charon_lib/">Charon Lib APIs</a>
+    </li>
+    <li>
+      <a href="./rustc/">Rustc Internal APIs</a> (nightly-xxxx-xx-xx) required by Charon
+    </li>
+  </ul>
+</body>
+
+</html>
diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml
index 83edc9493..4ac320cee 100644
--- a/.github/workflows/doc.yml
+++ b/.github/workflows/doc.yml
@@ -14,13 +14,32 @@ jobs:
       - name: Build static files
         env:
           CARGO_TERM_COLOR: always
-        id: build
         run: |
           cd charon
           make doc
 
+      - name: Install rustc internal docs
+        run: |
+          rustup toolchain list -v
+          # Find toolchain path
+          export TOOLCHAIN=$(rustc --print sysroot)
+          echo "toolchain=\"$TOOLCHAIN\""
+          # Remove rustc book
+          rm $TOOLCHAIN/share/doc/rust/html/rustc -rf
+          # Download rustc API docs
+          rustup component add rustc-docs
+          # Move the docs to deployment path
+          mv $TOOLCHAIN/share/doc/rust/html/rustc charon/target/doc/rustc
+
+      - name: Prepare index.html
+        run: |
+          # Find toolchain name
+          export toolchain=$(rustc --print sysroot | grep -oP "nightly-\d{4}-\d{2}-\d{2}")
+          echo "toolchain=\"$toolchain\""
+          # Fill in toolchain placeholder in index.html
+          sed "s/nightly-xxxx-xx-xx/$toolchain/" .github/index.html > charon/target/doc/index.html
+
       - name: Upload static files as artifact
-        id: deployment
         uses: actions/upload-pages-artifact@v3 # or specific "vX.X.X" version tag for this action
         with:
           path: charon/target/doc/


Reviews:
user: login: Nadrieril
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-03-17T13:48:22Z
user: login: zjp-CN
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-17T13:51:33Z
user: login: Nadrieril
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-03-17T13:52:49Z
user: login: zjp-CN
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-17T13:57:31Z
user: login: zjp-CN
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-17T14:00:50Z

Review comments:
diff_hunk: @@ -14,13 +14,24 @@ jobs:
       - name: Build static files
         env:
           CARGO_TERM_COLOR: always
-        id: build
         run: |
           cd charon
           make doc
 
+      - name: Install rustc internal docs
+        run: |
+          rustup toolchain list -v
+          # Find toolchain path
+          export TOOLCHAIN=$(rustup toolchain list -v | grep active | awk '{print $NF}')
path: .github/workflows/doc.yml
user: login: Nadrieril
body: That command doesn't work on my machine. I think `$(rustc --print sysroot)/share/doc/...` would work more more robustly.
created_at: 2025-03-17T13:48:22Z
author_association: MEMBER
diff_hunk: @@ -14,13 +14,24 @@ jobs:
       - name: Build static files
         env:
           CARGO_TERM_COLOR: always
-        id: build
         run: |
           cd charon
           make doc
 
+      - name: Install rustc internal docs
+        run: |
+          rustup toolchain list -v
+          # Find toolchain path
+          export TOOLCHAIN=$(rustup toolchain list -v | grep active | awk '{print $NF}')
path: .github/workflows/doc.yml
user: login: zjp-CN
body: It also doesn't work on my machine, because the pattern string for grep is `override` if multiple toolchains are installed...

I changed that due to github runner behavior.



> I think `$(rustc --print sysroot)/share/doc/...` would more more robustly.

Good idea. I'll update it.
created_at: 2025-03-17T13:51:32Z
author_association: CONTRIBUTOR
diff_hunk: @@ -23,14 +23,22 @@ jobs:
           rustup toolchain list -v
           # Find toolchain path
           export TOOLCHAIN=$(rustup toolchain list -v | grep active | awk '{print $NF}')
-          echo "toolchain=$TOOLCHAIN"
+          echo "toolchain=\"$TOOLCHAIN\""
           # Remove rustc book
           rm $TOOLCHAIN/share/doc/rust/html/rustc -rf
           # Download rustc API docs
           rustup component add rustc-docs
           # Move the docs to deployment path
           mv $TOOLCHAIN/share/doc/rust/html/rustc charon/target/doc/rustc
 
+      - name: Prepare index.html
+        run: |
+          # Find toolchain name
+          export toolchain=$(rustup toolchain list | grep active | grep -oP "nightly-\d{4}-\d{2}-\d{2}")
path: .github/workflows/doc.yml
user: login: Nadrieril
body: Same here, the toolchain name can be found in the `./rust-toolchain` toml file. Try:
```bash
cargo install toml2json
toolchain="$(toml2json rust-toolchain | jq -r .toolchain.channel)"
```
created_at: 2025-03-17T13:52:49Z
author_association: MEMBER
diff_hunk: @@ -23,14 +23,22 @@ jobs:
           rustup toolchain list -v
           # Find toolchain path
           export TOOLCHAIN=$(rustup toolchain list -v | grep active | awk '{print $NF}')
-          echo "toolchain=$TOOLCHAIN"
+          echo "toolchain=\"$TOOLCHAIN\""
           # Remove rustc book
           rm $TOOLCHAIN/share/doc/rust/html/rustc -rf
           # Download rustc API docs
           rustup component add rustc-docs
           # Move the docs to deployment path
           mv $TOOLCHAIN/share/doc/rust/html/rustc charon/target/doc/rustc
 
+      - name: Prepare index.html
+        run: |
+          # Find toolchain name
+          export toolchain=$(rustup toolchain list | grep active | grep -oP "nightly-\d{4}-\d{2}-\d{2}")
path: .github/workflows/doc.yml
user: login: zjp-CN
body: Would you mind using https://github.com/taiki-e/install-action?tab=readme-ov-file#supported-tools to install toml2json? The action saves installing it from compiling from source code, it may download toml2json from github via cargo-binstall instead.
created_at: 2025-03-17T13:57:30Z
author_association: CONTRIBUTOR
diff_hunk: @@ -23,14 +23,22 @@ jobs:
           rustup toolchain list -v
           # Find toolchain path
           export TOOLCHAIN=$(rustup toolchain list -v | grep active | awk '{print $NF}')
-          echo "toolchain=$TOOLCHAIN"
+          echo "toolchain=\"$TOOLCHAIN\""
           # Remove rustc book
           rm $TOOLCHAIN/share/doc/rust/html/rustc -rf
           # Download rustc API docs
           rustup component add rustc-docs
           # Move the docs to deployment path
           mv $TOOLCHAIN/share/doc/rust/html/rustc charon/target/doc/rustc
 
+      - name: Prepare index.html
+        run: |
+          # Find toolchain name
+          export toolchain=$(rustup toolchain list | grep active | grep -oP "nightly-\d{4}-\d{2}-\d{2}")
path: .github/workflows/doc.yml
user: login: zjp-CN
body: Or rather `rustc --print sysroot | grep -oP "nightly-\d{4}-\d{2}-\d{2}"` just works.
created_at: 2025-03-17T14:00:50Z
author_association: CONTRIBUTOR

PR comments:
user: login: zjp-CN
created_at: 2025-03-17T14:40:37Z
body: Is `Build and test / aeneas` workflow cancelled manually?

https://github.com/AeneasVerif/charon/actions/runs/13901881259/job/38895434672 seems to be blamed?
author_association: CONTRIBUTOR
user: login: Nadrieril
created_at: 2025-03-17T14:44:54Z
body: Oh well spotted, I didn't think that `rerun` would cancel things, I'll have to fix that.
author_association: MEMBER
user: login: zjp-CN
created_at: 2025-03-17T14:48:21Z
body: Yay, https://aeneasverif.github.io/charon looks right!
author_association: CONTRIBUTOR
user: login: Nadrieril
created_at: 2025-03-17T15:03:33Z
body: :tada: :tada: 
author_association: MEMBER