add versioning to mkdocs

Pipfile

@@ -8,6 +8,7 @@ name = "pypi"
 pipenv = "==2024.0.1"
 
 # Used for the published GitHub pages site:
+mike = "==2.1.2"
 mkdocs = "==1.5.3"
 mkdocs-literate-nav = "==0.6.1"
 mkdocs-material = "==9.5.17"

crates/infra/cli/Cargo.toml

@@ -21,7 +21,6 @@ serde_json = { workspace = true }
 strum = { workspace = true }
 strum_macros = { workspace = true }
 tempfile = { workspace = true }
-toml = { workspace = true }
 
 [lints]
 workspace = true

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

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

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

@@ -5,6 +5,7 @@ use clap::{Parser, ValueEnum};
 use infra_utils::commands::Command;
 use infra_utils::github::GitHub;
 use infra_utils::paths::{FileWalker, PathExtensions};
+use infra_utils::pipenv::PipEnv;
 use infra_utils::terminal::Terminal;
 
 use crate::utils::{ClapExtensions, OrderedCommand};
@@ -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/publish/cargo/mod.rs

@@ -5,12 +5,9 @@ use anyhow::Result;
 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;
-
 const USER_FACING_CRATES: &[&str] = &[
     // Sorted by dependency order (from dependencies to dependents):
     "metaslang_cst",
@@ -19,7 +16,7 @@ const USER_FACING_CRATES: &[&str] = &[
     "slang_solidity",
 ];
 
-pub fn publish_cargo(dry_run: DryRun) -> Result<()> {
+pub fn publish_cargo(dry_run: bool) -> Result<()> {
     let mut changeset = TemporaryChangeset::new(
         "infra/cargo-publish",
         "prepare Cargo packages for publishing",
@@ -114,16 +111,13 @@ fn update_cargo_lock(changeset: &mut TemporaryChangeset) -> Result<()> {
     Ok(())
 }
 
-fn run_cargo_publish(crate_name: &str, dry_run: DryRun) -> Result<()> {
+fn run_cargo_publish(crate_name: &str, dry_run: bool) -> Result<()> {
     let mut command = Command::new("cargo")
         .arg("publish")
         .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 {
         command = command.flag("--dry-run");
     }
 

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

@@ -8,9 +8,7 @@ use itertools::Itertools;
 use markdown::{Block, Span};
 use semver::Version;
 
-use crate::commands::publish::DryRun;
-
-pub fn publish_github_release(dry_run: DryRun) -> Result<()> {
+pub fn publish_github_release(dry_run: bool) -> Result<()> {
     let current_version = CargoWorkspace::local_version()?;
     println!("Current version: {current_version}");
 
@@ -30,8 +28,8 @@ pub fn publish_github_release(dry_run: DryRun) -> Result<()> {
     println!("{}", notes.lines().map(|l| format!("  │ {l}")).join("\n"));
     println!();
 
-    if dry_run.is_yes() || !GitHub::is_running_in_ci() {
-        println!("Skipping release, since we are not running in CI or a dry run was requested.");
+    if dry_run {
+        println!("Skipping release, because of the dry run.");
         return Ok(());
     }
 

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

@@ -0,0 +1,7 @@
+use anyhow::Result;
+
+use crate::toolchains::mkdocs::Mkdocs;
+
+pub fn publish_mkdocs(dry_run: bool) -> Result<()> {
+    Mkdocs::publish(dry_run)
+}

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

@@ -1,15 +1,18 @@
 mod cargo;
 mod changesets;
 mod github_release;
+mod mkdocs;
 mod npm;
 
 use anyhow::Result;
 use clap::{Parser, ValueEnum};
+use infra_utils::github::GitHub;
 use infra_utils::terminal::Terminal;
 
 use crate::commands::publish::cargo::publish_cargo;
 use crate::commands::publish::changesets::publish_changesets;
 use crate::commands::publish::github_release::publish_github_release;
+use crate::commands::publish::mkdocs::publish_mkdocs;
 use crate::commands::publish::npm::publish_npm;
 use crate::utils::ClapExtensions;
 
@@ -21,32 +24,12 @@ pub struct PublishController {
     dry_run: bool,
 }
 
-#[derive(Clone, Copy)]
-enum DryRun {
-    Yes,
-    No,
-}
-
-impl DryRun {
-    fn is_yes(self) -> bool {
-        matches!(self, DryRun::Yes)
-    }
-}
-
-impl From<bool> for DryRun {
-    fn from(value: bool) -> Self {
-        if value {
-            DryRun::Yes
-        } else {
-            DryRun::No
-        }
-    }
-}
-
 #[derive(Clone, Debug, Eq, Ord, PartialEq, PartialOrd, ValueEnum)]
 enum PublishCommand {
     /// Consume pending changesets, update changelogs and package versions, then send a PR.
     Changesets,
+    // Publish the documentation to GitHub pages.
+    Mkdocs,
     /// Publish source packages to [npmjs.com].
     Npm,
     /// Publish source crates to [crates.io].
@@ -59,10 +42,19 @@ impl PublishController {
     pub fn execute(&self) -> Result<()> {
         Terminal::step(format!("publish {name}", name = self.command.clap_name()));
 
-        let dry_run = DryRun::from(self.dry_run);
+        let dry_run = if self.dry_run {
+            println!("Attempting a dry run, since it was requested on the command line.");
+            true
+        } else if !GitHub::is_running_in_ci() {
+            println!("Attempting a dry run, since we are not running in CI.");
+            true
+        } else {
+            false
+        };
 
         match self.command {
             PublishCommand::Changesets => publish_changesets(),
+            PublishCommand::Mkdocs => publish_mkdocs(dry_run),
             PublishCommand::Npm => publish_npm(dry_run),
             PublishCommand::Cargo => publish_cargo(dry_run),
             PublishCommand::GithubRelease => publish_github_release(dry_run),

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

@@ -2,15 +2,13 @@ use std::path::Path;
 
 use anyhow::Result;
 use infra_utils::commands::Command;
-use infra_utils::github::GitHub;
 use infra_utils::paths::PathExtensions;
 
-use crate::commands::publish::DryRun;
 use crate::toolchains::napi::{
     NapiCompiler, NapiConfig, NapiPackageKind, NapiProfile, NapiResolver,
 };
 
-pub fn publish_npm(dry_run: DryRun) -> Result<()> {
+pub fn publish_npm(dry_run: bool) -> Result<()> {
     let resolver = NapiResolver::Solidity;
 
     NapiCompiler::run(resolver, NapiProfile::Release)?;
@@ -37,7 +35,7 @@ fn publish_package(
     resolver: NapiResolver,
     package_dir: &Path,
     kind: &NapiPackageKind,
-    dry_run: DryRun,
+    dry_run: bool,
 ) -> Result<()> {
     println!("Publishing: {package_dir:?}");
 
@@ -58,8 +56,7 @@ fn publish_package(
         .args(["publish", output_dir.unwrap_str()])
         .property("--access", "public");
 
-    if dry_run.is_yes() || !GitHub::is_running_in_ci() {
-        println!("Doing a dry run, since we are not running in CI or a dry run was requested.");
+    if dry_run {
         command = command.flag("--dry-run");
     }
 

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

@@ -1,52 +1,6 @@
-use std::collections::HashMap;
-use std::path::Path;
-
-use anyhow::{Context, Result};
-use infra_utils::commands::Command;
-use infra_utils::github::GitHub;
-use infra_utils::paths::PathExtensions;
-use serde::Deserialize;
+use anyhow::Result;
+use infra_utils::pipenv::PipEnv;
 
 pub fn setup_pipenv() -> Result<()> {
-    // Install the 'pipenv' binary using the version defined in the `Pipfile`.
-    install_pipenv_binary()?;
-
-    // Use it to install other dependencies:
-    install_project_packages()?;
-
-    Ok(())
-}
-
-#[derive(Deserialize)]
-struct Pipfile {
-    packages: HashMap<String, String>,
-}
-
-fn install_pipenv_binary() -> Result<()> {
-    let pip_file_toml = Path::repo_path("Pipfile").read_to_string()?;
-    let pip_file: Pipfile = toml::from_str(&pip_file_toml)?;
-
-    // This should be a value like "==YYYY.MM.DD"
-    let version = pip_file
-        .packages
-        .get("pipenv")
-        .context("Failed to find 'pipenv' in 'Pipfile' packages.")?;
-
-    // pip3 install "pipenv==YYYY.MM.DD"
-    Command::new("pip3")
-        .arg("install")
-        .arg(format!("pipenv{version}"))
-        .run()
-}
-
-fn install_project_packages() -> Result<()> {
-    let mut command = Command::new("python3")
-        .property("-m", "pipenv")
-        .arg("install");
-
-    if GitHub::is_running_in_ci() {
-        command = command.flag("--deploy");
-    }
-
-    command.run()
+    PipEnv::install_packages()
 }

crates/infra/cli/src/toolchains/mkdocs/mod.rs

@@ -3,34 +3,53 @@ use std::path::Path;
 use anyhow::Result;
 use infra_utils::commands::Command;
 use infra_utils::paths::PathExtensions;
+use infra_utils::pipenv::PipEnv;
 
 pub struct Mkdocs;
 
 impl Mkdocs {
-    pub fn build() -> Result<()> {
-        mkdocs_command()
-            .arg("build")
-            .flag("--clean")
-            .flag("--strict")
-            .run()
+    pub fn check() -> Result<()> {
+        mkdocs().arg("build").flag("--clean").flag("--strict").run()
     }
 
     pub fn watch() -> Result<()> {
         // _MKDOCS_WATCH_PORT_ | keep in sync with the port number defined in "$REPO_ROOT/.devcontainer/devcontainer.json"
         const PORT: usize = 5353;
 
-        mkdocs_command()
+        mkdocs()
             .arg("serve")
             .flag("--clean")
             .flag("--watch-theme")
             .property("--dev-addr", format!("localhost:{PORT}"))
             .run()
     }
+
+    pub fn publish(dry_run: bool) -> Result<()> {
+        Command::new("git")
+            .args(["fetch", "origin", "gh-pages"])
+            .property("--depth", "1")
+            .run()?;
+
+        // only once:
+        // mike set-default [identifier]
+
+        //   # git config user.name ci-bot
+        //   # git config user.email [email protected]
+
+        //   - run: "python3 -m pipenv run mike deploy main"
+        //   if (dry_run) add "--push" to the "deploy" command
+
+        //     # or:
+        //     # use 'mike list [identifier]' first to check if the version exists
+        //     # - run: "python3 -m pipenv run mike deploy 0.15.0 latest --update-aliases --push"
+        //   if (dry_run) add "--push" to the "deploy" command
+    }
+}
+
+fn mkdocs() -> Command {
+    PipEnv::run("mkdocs").current_dir(Path::repo_path("documentation"))
 }
 
-fn mkdocs_command() -> Command {
-    Command::new("python3")
-        .property("-m", "pipenv")
-        .args(["run", "mkdocs"])
-        .current_dir(Path::repo_path("documentation"))
+fn mike() -> Command {
+    PipEnv::run("mike").current_dir(Path::repo_path("documentation"))
 }

crates/infra/utils/src/lib.rs

@@ -4,4 +4,5 @@ pub mod commands;
 pub mod git;
 pub mod github;
 pub mod paths;
+pub mod pipenv;
 pub mod terminal;