add versioning to mkdocs

.github/workflows/publish.yml

@@ -34,11 +34,11 @@ jobs:
       - name: "Restore Cache"
         uses: "./.github/actions/cache/restore"
 
-      - name: "infra setup pipenv"
+      - name: "infra setup git pipenv"
         uses: "./.devcontainer"
         with:
           entrypoint: "./scripts/bin/infra"
-          args: "setup pipenv"
+          args: "setup git pipenv"
 
       - name: "infra check mkdocs"
         uses: "./.devcontainer"
@@ -86,11 +86,11 @@ jobs:
       - name: "Restore Cache"
         uses: "./.github/actions/cache/restore"
 
-      - name: "infra setup cargo npm"
+      - name: "infra setup git cargo npm"
         uses: "./.devcontainer"
         with:
           entrypoint: "./scripts/bin/infra"
-          args: "setup cargo npm"
+          args: "setup git cargo npm"
 
       - name: "infra publish changesets"
         uses: "./.devcontainer"
@@ -127,11 +127,11 @@ jobs:
       - name: "Restore Cache"
         uses: "./.github/actions/cache/restore"
 
-      - name: "infra setup cargo npm"
+      - name: "infra setup git cargo npm"
         uses: "./.devcontainer"
         with:
           entrypoint: "./scripts/bin/infra"
-          args: "setup cargo npm"
+          args: "setup git cargo npm"
 
       - name: "infra publish npm"
         uses: "./.devcontainer"

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/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

@@ -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/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/git/mod.rs

@@ -0,0 +1,22 @@
+use anyhow::Result;
+use infra_utils::commands::Command;
+use infra_utils::github::GitHub;
+
+pub fn setup_git() -> Result<()> {
+    if !GitHub::is_running_in_ci() {
+        println!("No need to modify local dev environments.");
+        return Ok(());
+    }
+
+    Command::new("git")
+        .arg("config")
+        .property("user.name", "github-actions")
+        .run()?;
+
+    Command::new("git")
+        .arg("config")
+        .property("user.email", "[email protected]")
+        .run()?;
+
+    Ok(())
+}

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

@@ -1,4 +1,5 @@
 mod cargo;
+mod git;
 mod npm;
 mod pipenv;
 mod shell_completions;
@@ -9,6 +10,7 @@ use infra_utils::terminal::Terminal;
 
 use crate::commands::setup::cargo::setup_cargo;
 use crate::commands::setup::npm::setup_npm;
+use crate::commands::setup::git::setup_git;
 use crate::commands::setup::pipenv::setup_pipenv;
 use crate::commands::setup::shell_completions::setup_shell_completions;
 use crate::utils::{ClapExtensions, OrderedCommand};
@@ -27,6 +29,8 @@ impl SetupController {
 
 #[derive(Clone, Debug, Eq, Ord, PartialEq, PartialOrd, ValueEnum)]
 enum SetupCommand {
+    /// Prepare the local git client/repository.
+    Git,
     /// Install Cargo dependencies.
     Cargo,
     /// Install NPM dependencies.
@@ -42,6 +46,7 @@ impl OrderedCommand for SetupCommand {
         Terminal::step(format!("setup {name}", name = self.clap_name()));
 
         match self {
+            SetupCommand::Git => setup_git(),
             SetupCommand::Cargo => setup_cargo(),
             SetupCommand::Npm => setup_npm(),
             SetupCommand::Pipenv => setup_pipenv(),

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

@@ -1,52 +1,7 @@
-use std::collections::HashMap;
-use std::path::Path;
+use anyhow::Result;
 
-use anyhow::{Context, Result};
-use infra_utils::commands::Command;
-use infra_utils::github::GitHub;
-use infra_utils::paths::PathExtensions;
-use serde::Deserialize;
+use crate::toolchains::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()
 }