publish docs to /docs/main

.github/workflows/publish-to-pages.yaml

@@ -0,0 +1,41 @@
+name: publish to github pages
+
+on:
+  push:
+    branches: [ main ]
+
+# Cancel already running jobs
+concurrency:
+  group: publish_to_pages_${{ github.head_ref }}
+  cancel-in-progress: true
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build:
+    strategy:
+      matrix:
+        include:
+          - name: Publish website to Github Pages
+            runner: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.setup_pages.outputs.base_url }}
+    name: ${{ matrix.name }}
+    runs-on: ${{ matrix.runner }}
+    steps:
+    - uses: actions/checkout@v4
+    - name: Build website
+      run: cargo run -p website
+    - name: Setup Pages
+      uses: actions/configure-pages@v4
+    - name: Upload pages
+      uses: actions/upload-pages-artifact@v3
+      with:
+        path: 'website/root'
+    - name: Deploy pages
+      uses: actions/deploy-pages@v4

.gitignore

@@ -10,6 +10,8 @@
 /.project
 /docs/book
 /docs/mdbook_bin
+/website/root
+/website/shotover_repo_for_docs
 /shotover-proxy/build/packages
 /some_local_file
 /test-helpers/src/connection/kafka/node/node_modules

Cargo.toml

@@ -6,6 +6,7 @@ members = [
     "custom-transforms-example",
     "ec2-cargo",
     "windsock-cloud-docker",
+    "website",
 ]
 resolver = "2"
 

docs/book.toml

@@ -7,9 +7,9 @@ title = "Shotover"
 
 [output.html]
 
-[output.linkcheck]
+#[output.linkcheck]
 # Should we check links on the internet? Enabling this option adds a
 # non-negligible performance impact
-follow-web-links = false
+#follow-web-links = false
 
 warning-policy = "error"

docs/mdbook.sh

@@ -6,8 +6,10 @@ set -e; set -u
 if [ ! -d "mdbook_bin" ]; then
     mkdir -p mdbook_bin
     pushd mdbook_bin
-    curl -L https://github.com/rust-lang/mdBook/releases/download/v0.4.13/mdbook-v0.4.13-x86_64-unknown-linux-gnu.tar.gz | tar xvz
-    wget https://github.com/Michael-F-Bryan/mdbook-linkcheck/releases/download/v0.7.6/mdbook-linkcheck.x86_64-unknown-linux-gnu.zip -O linkcheck.zip
+    #curl -L https://github.com/rust-lang/mdBook/releases/download/v0.4.13/mdbook-v0.4.13-x86_64-unknown-linux-gnu.tar.gz | tar xvz
+    curl -L https://github.com/rust-lang/mdBook/releases/download/v0.4.13/mdbook-v0.4.13-x86_64-apple-darwin-gnu.tar.gz | tar -xvz
+    chmod +x mdbook
+    curl https://github.com/Michael-F-Bryan/mdbook-linkcheck/releases/download/v0.7.6/mdbook-linkcheck.x86_64-unknown-linux-gnu.zip -o linkcheck.zip
     unzip linkcheck.zip
     chmod +x mdbook-linkcheck
     popd

website/Cargo.toml

@@ -0,0 +1,12 @@
+[package]
+name = "website"
+version = "0.1.0"
+edition = "2021"
+license = "Apache-2.0"
+publish = false
+
+[dependencies]
+subprocess.workspace = true
+anyhow.workspace = true
+rinja = "0.3.5"
+semver = "1.0.23"

website/src/main.rs

@@ -0,0 +1,123 @@
+use anyhow::{anyhow, Result};
+use rinja::Template;
+use std::{path::Path, process::Command};
+use subprocess::{Exec, Redirection};
+
+mod version_tags;
+
+fn main() {
+    // Set standard path to root of repo so this always runs in the same directory, regardless of where the user ran it from.
+    let current_dir = Path::new(env!("CARGO_MANIFEST_DIR")).parent().unwrap();
+    std::env::set_current_dir(current_dir).unwrap();
+
+    println!("Ensuring mdbook is installed");
+    // TODO: Once mdbook starts doing macos aarch64 binary releases we should download the release directly instead of compiling.
+    //       https://github.com/rust-lang/mdBook/pull/2500
+    if !Command::new("cargo")
+        .args(["install", "mdbook", "--version", "0.4.43"])
+        .status()
+        .unwrap()
+        .success()
+    {
+        return;
+    }
+
+    if let Err(err) = run(current_dir) {
+        println!("{err}");
+        return;
+    }
+
+    let out = current_dir
+        .join("website")
+        .join("root")
+        .join("docs")
+        .join("index.html");
+    println!(
+        "Succesfully generated website at: file://{}",
+        out.to_str().unwrap()
+    );
+}
+
+fn run(current_dir: &Path) -> Result<()> {
+    let root = current_dir.join("website").join("root");
+    run_command("docs", "mdbook", &["test"])?;
+    run_command(
+        "docs",
+        "mdbook",
+        &[
+            "build",
+            "--dest-dir",
+            root.join("docs").join("main").to_str().unwrap(),
+        ],
+    )?;
+
+    // ensure repo exists and is up to date
+    let repo_path = Path::new("website").join("shotover_repo_for_docs");
+    if repo_path.exists() {
+        run_command(&repo_path, "git", &["fetch"])?;
+    } else {
+        run_command(
+            ".",
+            "git",
+            &[
+                "clone",
+                "https://github.com/shotover/shotover-proxy",
+                repo_path.to_str().unwrap(),
+            ],
+        )?;
+    }
+
+    let versions = version_tags::get_versions_of_repo(&repo_path);
+
+    let docs = DocsTemplate {
+        versions: versions.iter().map(|x| x.semver_range.clone()).collect(),
+    };
+    std::fs::write(root.join("docs").join("index.html"), docs.render().unwrap()).unwrap();
+
+    for version in &versions {
+        println!("Generating {}", version.tag);
+        run_command(&repo_path, "git", &["checkout", &version.tag])?;
+
+        let temp_docs_dir = root.join("temp_docs_build");
+        std::fs::remove_dir_all(&temp_docs_dir).ok();
+        run_command(
+            repo_path.join("docs"),
+            "mdbook",
+            &["build", "--dest-dir", temp_docs_dir.to_str().unwrap()],
+        )
+        .ok();
+
+        let version_docs_dest = root.join("docs").join(&version.semver_range);
+        std::fs::remove_dir_all(&version_docs_dest).ok();
+        std::fs::rename(temp_docs_dir.join("html"), version_docs_dest).unwrap();
+    }
+
+    Ok(())
+}
+
+pub fn run_command(dir: impl AsRef<Path>, command: &str, args: &[&str]) -> Result<String> {
+    let data = Exec::cmd(command)
+        .args(args)
+        .cwd(dir)
+        .stdout(Redirection::Pipe)
+        .stderr(Redirection::Merge)
+        .capture()?;
+
+    if data.exit_status.success() {
+        Ok(data.stdout_str())
+    } else {
+        Err(anyhow!(
+            "command {} {:?} exited with {:?} and output:\n{}",
+            command,
+            args,
+            data.exit_status,
+            data.stdout_str()
+        ))
+    }
+}
+
+#[derive(Template)]
+#[template(path = "docs.html")]
+struct DocsTemplate {
+    versions: Vec<String>,
+}