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");
  }