Merge pull request #3034 from rtfeldman/skip-code-gen-for-netlify

Introduce `roc-docs` CLI just for Netlify builds

Cargo.lock

@@ -3663,6 +3663,14 @@ dependencies = [
  "snafu",
 ]
 
+[[package]]
+name = "roc_docs_cli"
+version = "0.1.0"
+dependencies = [
+ "clap 3.1.17",
+ "roc_docs",
+]
+
 [[package]]
 name = "roc_editor"
 version = "0.1.0"

Cargo.toml

@@ -46,6 +46,7 @@ members = [
     "test_utils",
     "utils",
     "docs",
+    "docs_cli",
     "linker",
     "wasi-libc-sys",
 ]

Earthfile

@@ -53,7 +53,7 @@ install-zig-llvm-valgrind-clippy-rustfmt:
 
 copy-dirs:
     FROM +install-zig-llvm-valgrind-clippy-rustfmt
-    COPY --dir bindgen cli cli_utils compiler docs editor ast code_markup error_macros highlight utils test_utils reporting repl_cli repl_eval repl_test repl_wasm repl_www roc_std vendor examples linker Cargo.toml Cargo.lock version.txt www wasi-libc-sys ./
+    COPY --dir bindgen cli cli_utils compiler docs docs_cli editor ast code_markup error_macros highlight utils test_utils reporting repl_cli repl_eval repl_test repl_wasm repl_www roc_std vendor examples linker Cargo.toml Cargo.lock version.txt www wasi-libc-sys ./
 
 test-zig:
     FROM +install-zig-llvm-valgrind-clippy-rustfmt

cli/src/lib.rs

@@ -11,7 +11,7 @@ use roc_mono::ir::OptLevel;
 use std::env;
 use std::ffi::OsStr;
 use std::io;
-use std::path::{Path, PathBuf};
+use std::path::Path;
 use std::process;
 use target_lexicon::BinaryFormat;
 use target_lexicon::{
@@ -204,7 +204,6 @@ pub fn build_app<'a>() -> Command<'a> {
             Command::new(CMD_DOCS)
                 .about("Generate documentation for Roc modules (Work In Progress)")
                 .arg(Arg::new(DIRECTORY_OR_FILES)
-                    .index(1)
                     .multiple_values(true)
                     .required(false)
                     .help("The directory or files to build documentation for")
@@ -230,7 +229,6 @@ pub fn build_app<'a>() -> Command<'a> {
                 .about("Launch the Roc editor (Work In Progress)")
                 .arg(
                     Arg::new(DIRECTORY_OR_FILES)
-                        .index(1)
                         .multiple_values(true)
                         .required(false)
                         .help("(optional) The directory or files to open on launch."),
@@ -241,10 +239,6 @@ pub fn build_app<'a>() -> Command<'a> {
     }
 }
 
-pub fn docs(files: Vec<PathBuf>) {
-    roc_docs::generate_docs_html(files, Path::new("./generated-docs"))
-}
-
 #[derive(Debug, PartialEq, Eq)]
 pub enum BuildConfig {
     BuildOnly,

cli/src/main.rs

@@ -1,10 +1,11 @@
 use roc_build::link::LinkType;
 use roc_cli::build::check_file;
 use roc_cli::{
-    build_app, docs, format, BuildConfig, FormatMode, Target, CMD_BUILD, CMD_CHECK, CMD_DOCS,
-    CMD_EDIT, CMD_FORMAT, CMD_REPL, CMD_RUN, CMD_VERSION, DIRECTORY_OR_FILES, FLAG_CHECK, FLAG_LIB,
+    build_app, format, BuildConfig, FormatMode, Target, CMD_BUILD, CMD_CHECK, CMD_DOCS, CMD_EDIT,
+    CMD_FORMAT, CMD_REPL, CMD_RUN, CMD_VERSION, DIRECTORY_OR_FILES, FLAG_CHECK, FLAG_LIB,
     FLAG_NO_LINK, FLAG_TARGET, FLAG_TIME, ROC_FILE,
 };
+use roc_docs::generate_docs_html;
 use roc_error_macros::user_error;
 use roc_load::{LoadingProblem, Threading};
 use std::fs::{self, FileType};
@@ -193,7 +194,7 @@ fn main() -> io::Result<()> {
                 roc_files_recursive(os_str.as_os_str(), metadata.file_type(), &mut roc_files)?;
             }
 
-            docs(roc_files);
+            generate_docs_html(roc_files);
 
             Ok(0)
         }

docs/Cargo.toml

@@ -5,8 +5,6 @@ license = "UPL-1.0"
 authors = ["The Roc Contributors"]
 edition = "2018"
 
-# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
-
 [dependencies]
 pulldown-cmark = { version = "0.8.0", default-features = false }
 roc_ast = { path = "../ast" }

docs/src/lib.rs

@@ -21,7 +21,10 @@ use std::path::{Path, PathBuf};
 mod docs_error;
 mod html;
 
-pub fn generate_docs_html(filenames: Vec<PathBuf>, build_dir: &Path) {
+const BUILD_DIR: &str = "./generated-docs";
+
+pub fn generate_docs_html(filenames: Vec<PathBuf>) {
+    let build_dir = Path::new(BUILD_DIR);
     let loaded_modules = load_modules_for_files(filenames);
 
     // TODO: get info from a package module; this is all hardcoded for now.

docs_cli/Cargo.toml

@@ -0,0 +1,21 @@
+[package]
+name = "roc_docs_cli"
+version = "0.1.0"
+license = "UPL-1.0"
+authors = ["The Roc Contributors"]
+edition = "2018"
+
+# This binary is only used on static build servers, e.g. Netlify.
+# Having its own (extremely minimal) CLI means docs can be generated
+# on a build server after building this crate from source, without
+# having to install non-Rust dependencies (LLVM, Zig, wasm things, etc.)
+# It gets called in www/build.sh via `cargo run --bin roc-docs`
+[[bin]]
+name = "roc-docs"
+path = "src/main.rs"
+test = false
+bench = false
+
+[dependencies]
+roc_docs = { path = "../docs" }
+clap = { version = "3.1.15", default-features = false, features = ["std", "color", "suggestions", "derive"] }

docs_cli/src/main.rs

@@ -0,0 +1,50 @@
+use clap::{Arg, Command};
+use roc_docs::generate_docs_html;
+use std::fs::{self, FileType};
+use std::io;
+use std::path::{Path, PathBuf};
+
+pub const DIRECTORY_OR_FILES: &str = "DIRECTORY_OR_FILES";
+
+fn main() -> io::Result<()> {
+    let matches = Command::new("roc-docs")
+        .about("Build HTML documentation files from the given .roc files")
+        .arg(
+            Arg::new(DIRECTORY_OR_FILES)
+                .multiple_values(true)
+                .required(true)
+                .help("The directory or files to build documentation for")
+                .allow_invalid_utf8(true),
+        )
+        .get_matches();
+
+    let mut roc_files = Vec::new();
+
+    // Populate roc_files
+    for os_str in matches.values_of_os(DIRECTORY_OR_FILES).unwrap() {
+        let metadata = fs::metadata(os_str)?;
+        roc_files_recursive(os_str, metadata.file_type(), &mut roc_files)?;
+    }
+
+    generate_docs_html(roc_files);
+
+    Ok(())
+}
+
+fn roc_files_recursive<P: AsRef<Path>>(
+    path: P,
+    file_type: FileType,
+    roc_files: &mut Vec<PathBuf>,
+) -> io::Result<()> {
+    if file_type.is_dir() {
+        for entry_res in fs::read_dir(path)? {
+            let entry = entry_res?;
+
+            roc_files_recursive(entry.path(), entry.file_type()?, roc_files)?;
+        }
+    } else {
+        roc_files.push(path.as_ref().to_path_buf());
+    }
+
+    Ok(())
+}

www/build.sh

@@ -50,7 +50,7 @@ BUILTINS_HOST_O=""
 # We run the CLI with --no-default-features because that way we don't have the
 # "llvm" feature and therefore don't depend on LLVM being installed on the
 # system. (Netlify's build servers have Rust installed, but not LLVM.)
-cargo run -p roc_cli --no-default-features docs compiler/builtins/roc/*.roc
+cargo run --bin roc-docs compiler/builtins/roc/*.roc
 mv generated-docs/*.* www/build # move all the .js, .css, etc. files to build/
 mv generated-docs/ www/build/builtins # move all the folders to build/builtins/
 popd