add versioning to mkdocs (NomicFoundation#1063)

Closes NomicFoundation#1022


![image](https://github.com/user-attachments/assets/751e2118-20a5-45d2-937c-22fbd877edd5)

![image](https://github.com/user-attachments/assets/ad96e31f-6bb5-403e-81f7-1c8f0c091af9)

.github/workflows/publish.yml

@@ -21,48 +21,7 @@ jobs:
     if: "${{ github.repository == 'NomicFoundation/slang' && github.ref_name == 'main' }}"
     uses: "./.github/workflows/ci.yml"
 
-  buildDocs:
-    runs-on: "ubuntu-22.04" # _SLANG_DEV_CONTAINER_BASE_IMAGE_ (keep in sync)
-    needs: "ci"
-
-    steps:
-      - name: "Checkout Repository"
-        uses: "actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332"
-
-      - name: "Restore Cache"
-        uses: "./.github/actions/cache/restore"
-
-      - name: "infra check mkdocs"
-        uses: "./.github/actions/devcontainer/run"
-        with:
-          runCmd: "./scripts/bin/infra check mkdocs"
-
-      - name: "Configure Pages"
-        uses: "actions/configure-pages@1f0c5cde4bc74cd7e1254d0cb4de8d49e9068c7d"
-
-      - name: "Upload Artifacts"
-        uses: "actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa"
-        with:
-          path: "documentation/target/site" # _SLANG_MKDOCS_DOCUMENTATION_SITE_DIR_ (keep in sync)
-
-  deployDocs:
-    runs-on: "ubuntu-22.04" # _SLANG_DEV_CONTAINER_BASE_IMAGE_ (keep in sync)
-    needs: "buildDocs"
-
-    permissions:
-      pages: "write" # to deploy to Pages
-      id-token: "write" # to verify the deployment originates from an appropriate source
-
-    steps:
-      - name: "Deploy Pages"
-        id: "deployment"
-        uses: "actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e"
-
-    environment:
-      name: "github-pages"
-      url: "${{ steps.deployment.outputs.page_url }}"
-
-  consumeChangesets:
+  publish:
     runs-on: "ubuntu-22.04" # _SLANG_DEV_CONTAINER_BASE_IMAGE_ (keep in sync)
     needs: "ci"
 
@@ -95,37 +54,39 @@ jobs:
         env:
           GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
 
-    outputs:
-      hasChangesets: "${{ steps.runChangesets.outputs.hasChangesets }}"
-
-  artifacts:
-    runs-on: "ubuntu-22.04" # _SLANG_DEV_CONTAINER_BASE_IMAGE_ (keep in sync)
-    needs: "consumeChangesets"
-
-    if: "${{ needs.consumeChangesets.outputs.hasChangesets == 'false' }}"
-
-    steps:
-      - name: "Checkout Repository"
-        uses: "actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332"
+      - name: "infra publish mkdocs --target main-branch"
+        uses: "./.github/actions/devcontainer/run"
+        with:
+          runCmd: "./scripts/bin/infra publish mkdocs --target main-branch"
+          env: |
+            GITHUB_TOKEN=${{ secrets.GITHUB_TOKEN }}
 
-      - name: "Restore Cache"
-        uses: "./.github/actions/cache/restore"
+      - name: "infra publish mkdocs --target latest-release"
+        if: "${{ steps.runChangesets.outputs.hasChangesets == 'false' }}"
+        uses: "./.github/actions/devcontainer/run"
+        with:
+          runCmd: "./scripts/bin/infra publish mkdocs --target latest-release"
+          env: |
+            GITHUB_TOKEN=${{ secrets.GITHUB_TOKEN }}
 
       - name: "infra publish npm"
+        if: "${{ steps.runChangesets.outputs.hasChangesets == 'false' }}"
         uses: "./.github/actions/devcontainer/run"
         with:
           runCmd: "./scripts/bin/infra publish npm"
           env: |
             NPM_TOKEN=${{ secrets.NPM_TOKEN }}
 
       - name: "infra publish cargo"
+        if: "${{ steps.runChangesets.outputs.hasChangesets == 'false' }}"
         uses: "./.github/actions/devcontainer/run"
         with:
           runCmd: "./scripts/bin/infra publish cargo"
           env: |
             CARGO_REGISTRY_TOKEN=${{ secrets.CARGO_REGISTRY_TOKEN }}
 
       - name: "infra publish github-release"
+        if: "${{ steps.runChangesets.outputs.hasChangesets == 'false' }}"
         uses: "./.github/actions/devcontainer/run"
         with:
           runCmd: "./scripts/bin/infra publish github-release"

Pipfile

@@ -8,9 +8,10 @@ name = "pypi"
 pipenv = "==2024.0.1"
 
 # Used for the published GitHub pages site:
-mkdocs = "==1.5.3"
+mike = "==2.1.2"
+mkdocs = "==1.6.0"
 mkdocs-literate-nav = "==0.6.1"
-mkdocs-material = "==9.5.17"
+mkdocs-material = "==9.5.31"
 mkdocs-minify-plugin = "==0.8.0"
 mkdocs-pymdownx-material-extras = "==2.5.6"
 

crates/infra/cli/src/commands/check/mod.rs

@@ -78,5 +78,5 @@ fn check_npm() -> Result<()> {
 }
 
 fn check_mkdocs() -> Result<()> {
-    Mkdocs::build()
+    Mkdocs::check()
 }

crates/infra/cli/src/commands/lint/mod.rs

@@ -7,6 +7,7 @@ use infra_utils::github::GitHub;
 use infra_utils::paths::{FileWalker, PathExtensions};
 use infra_utils::terminal::Terminal;
 
+use crate::toolchains::pipenv::PipEnv;
 use crate::utils::{ClapExtensions, OrderedCommand};
 
 #[derive(Clone, Debug, Default, Parser)]
@@ -143,9 +144,7 @@ fn run_yamllint() -> Result<()> {
             path
         });
 
-    return Command::new("python3")
-        .property("-m", "pipenv")
-        .args(["run", "yamllint"])
+    return PipEnv::run("yamllint")
         .flag("--strict")
         .property("--config-file", config_file.unwrap_str())
         .run_xargs(yaml_files);

crates/infra/cli/src/commands/mod.rs

@@ -71,16 +71,16 @@ impl Cli {
 impl AppCommand {
     pub fn execute(&self) -> Result<()> {
         match self {
-            AppCommand::Setup(command) => command.execute(),
-            AppCommand::Check(command) => command.execute(),
-            AppCommand::Test(command) => command.execute(),
-            AppCommand::Lint(command) => command.execute(),
-            AppCommand::Ci(command) => command.execute(),
-            AppCommand::Run(command) => command.execute(),
-            AppCommand::Watch(command) => command.execute(),
-            AppCommand::Perf(command) => command.execute(),
-            AppCommand::Publish(command) => command.execute(),
-            AppCommand::Completions(command) => command.execute(),
+            AppCommand::Setup(controller) => controller.execute(),
+            AppCommand::Check(controller) => controller.execute(),
+            AppCommand::Test(controller) => controller.execute(),
+            AppCommand::Lint(controller) => controller.execute(),
+            AppCommand::Ci(controller) => controller.execute(),
+            AppCommand::Run(controller) => controller.execute(),
+            AppCommand::Watch(controller) => controller.execute(),
+            AppCommand::Perf(controller) => controller.execute(),
+            AppCommand::Publish(controller) => controller.execute(),
+            AppCommand::Completions(controller) => controller.execute(),
         }
     }
 }

crates/infra/cli/src/commands/publish/cargo/mod.rs

@@ -2,14 +2,14 @@ use std::iter::once;
 use std::path::Path;
 
 use anyhow::Result;
+use clap::Parser;
 use infra_utils::cargo::CargoWorkspace;
 use infra_utils::commands::Command;
 use infra_utils::git::TemporaryChangeset;
-use infra_utils::github::GitHub;
 use infra_utils::paths::PathExtensions;
 use itertools::Itertools;
 
-use crate::commands::publish::DryRun;
+use crate::utils::DryRun;
 
 const USER_FACING_CRATES: &[&str] = &[
     // Sorted by dependency order (from dependencies to dependents):
@@ -19,36 +19,44 @@ const USER_FACING_CRATES: &[&str] = &[
     "slang_solidity",
 ];
 
-pub fn publish_cargo(dry_run: DryRun) -> Result<()> {
-    let mut changeset = TemporaryChangeset::new(
-        "infra/cargo-publish",
-        "prepare Cargo packages for publishing",
-    )?;
+#[derive(Clone, Debug, Parser)]
+pub struct CargoController {
+    #[command(flatten)]
+    dry_run: DryRun,
+}
+
+impl CargoController {
+    pub fn execute(&self) -> Result<()> {
+        let mut changeset = TemporaryChangeset::new(
+            "infra/cargo-publish",
+            "prepare Cargo packages for publishing",
+        )?;
 
-    let mut changed_crates = vec![];
+        let mut changed_crates = vec![];
 
-    for crate_name in USER_FACING_CRATES {
-        if prepare_for_publish(crate_name, &mut changeset)? {
-            changed_crates.push(crate_name);
+        for crate_name in USER_FACING_CRATES {
+            if prepare_for_publish(crate_name, &mut changeset)? {
+                changed_crates.push(crate_name);
+            }
         }
-    }
 
-    if changed_crates.is_empty() {
-        println!("No crates to publish.");
-        return Ok(());
-    }
+        if changed_crates.is_empty() {
+            println!("No crates to publish.");
+            return Ok(());
+        }
 
-    update_cargo_lock(&mut changeset)?;
+        update_cargo_lock(&mut changeset)?;
 
-    changeset.commit_changes()?;
+        changeset.commit_changes()?;
 
-    for crate_name in &changed_crates {
-        run_cargo_publish(crate_name, dry_run)?;
-    }
+        for crate_name in &changed_crates {
+            run_cargo_publish(crate_name, self.dry_run)?;
+        }
 
-    changeset.revert_changes()?;
+        changeset.revert_changes()?;
 
-    Ok(())
+        Ok(())
+    }
 }
 
 fn prepare_for_publish(crate_name: &str, changeset: &mut TemporaryChangeset) -> Result<bool> {
@@ -120,10 +128,7 @@ fn run_cargo_publish(crate_name: &str, dry_run: DryRun) -> Result<()> {
         .property("--package", crate_name)
         .flag("--all-features");
 
-    if dry_run.is_yes() || !GitHub::is_running_in_ci() {
-        println!(
-            "Attempting a dry run, since we are not running in CI or a dry run was requested."
-        );
+    if dry_run.get() {
         command = command.flag("--dry-run");
     }