Rewrite generate-errors and improve learn/errors (#1089)

Co-authored-by: BD103 <[email protected]>
Co-authored-by: Alice Cecile <[email protected]>

Author: 3 people

Cargo.lock

@@ -42,7 +42,7 @@ description = "Browse bevy examples compiled to wasm and running directly in you
 
 [[links]]
 title = "Bevy Errors"
-url = "/learn/errors"
+url = "/learn/errors/introduction"
 image = "/assets/bevy_icon_dark.svg"
 image_alt = "Bevy logo"
 description = "List of Bevy's error codes for the current release."

content/learn/links.toml

@@ -1,2 +1,5 @@
 # Bevy repository
 bevy/
+# Fake content folder for tests
+section_content/
+pages_content/

generate-errors/.gitignore

@@ -1,17 +1,17 @@
 [package]
 name = "generate-errors"
-version = "0.1.0"
+version = "0.2.0"
 authors = [
   "Bevy Contributors <[email protected]>",
   "Carter Anderson <[email protected]>",
 ]
 license = "MIT"
-edition = "2018"
-
-[dependencies]
-serde = { version = "1", features = [ "derive" ] }
-toml = "0.5"
-regex = "1.5"
+edition = "2021"
 
 [lints]
 workspace = true
+
+[dependencies]
+anyhow = "1.0.80"
+clap = { version = "4.5.2", features = ["derive"] }
+regex = "1.10.3"

generate-errors/Cargo.toml

@@ -0,0 +1,17 @@
+# Generate Errors
+
+This website utility tool takes the documentation of Bevy-unique error codes from the Bevy engine repo and makes them valid Zola pages.
+
+For most uses run the bash script from any directory:
+`./generate-errors/generate-errors.sh`
+or
+`./generate-errors.sh`
+
+## Niche Advice
+
+Almost certainly all use cases will be covered by the bash script above, but if you, for whatever reason, need to use the tool straight from cargo then you can run it like:
+`cargo run -- --errors-path <ERRORS_PATH> --output-path <OUTPUT_PATH>`
+Where `errors-path` is the directory containing the original error files in the Bevy repo. `output-path` is the folder that the errors section folder is output.
+
+You can also see the help page for the tool via:
+`cargo run -- -h` or `cargo run -- --help`

generate-errors/README.md

@@ -11,4 +11,4 @@ git sparse-checkout set "errors"
 git pull --depth=1 origin latest
 cd ..
 
-cargo run --bin generate -- bevy/errors ../content/learn
+cargo run --bin generate -- --errors-path bevy/errors --output-path ../content/learn

generate-errors/generate_errors.sh

@@ -1,113 +1,34 @@
-use generate_errors::{parse_errors, ErrorCode, FrontMatterErrorCode, Section};
-use serde::Serialize;
-use std::fs::File;
-use std::io::Write;
-use std::path::Path;
-use std::{fs, io};
-
-fn main() -> io::Result<()> {
-    let errors_dir = std::env::args()
-        .nth(1)
-        .expect("First argument should specify the errors directory");
-    let content_dir = std::env::args()
-        .nth(2)
-        .expect("Second argument should specify the content directory");
-    let _ = fs::create_dir(content_dir.clone());
-    let errors_root_section = parse_errors(&errors_dir)?;
-
-    errors_root_section.write(Path::new(&content_dir), Path::new(""), 0)
-}
-
-trait FrontMatterWriter {
-    fn write(&self, root_path: &Path, current_path: &Path, weight: usize) -> io::Result<()>;
-}
-
-#[derive(Serialize)]
-struct FrontMatterSection {
-    title: String,
-    sort_by: String,
-    template: Option<String>,
-    weight: usize,
-    extra: FrontMatterSectionExtra,
-}
-
-#[derive(Serialize)]
-struct FrontMatterSectionExtra {
-    header_message: Option<String>,
-    sort_order_reversed: bool,
-}
-
-impl From<&Section> for FrontMatterSection {
-    fn from(section: &Section) -> Self {
-        FrontMatterSection {
-            title: section.name.clone(),
-            sort_by: "weight".to_string(),
-            template: section.template.clone(),
-            weight: section.order.unwrap_or(0),
-            extra: section.into(),
-        }
-    }
-}
-
-impl From<&Section> for FrontMatterSectionExtra {
-    fn from(section: &Section) -> Self {
-        FrontMatterSectionExtra {
-            header_message: section.header.clone(),
-            sort_order_reversed: section.sort_order_reversed,
-        }
-    }
-}
-
-impl FrontMatterWriter for Section {
-    fn write(&self, root_path: &Path, current_path: &Path, weight: usize) -> io::Result<()> {
-        let section_path = current_path.join(self.name.to_ascii_lowercase());
-        let path = root_path.join(&section_path);
-        fs::create_dir(path.clone())?;
-
-        let mut frontmatter = FrontMatterSection::from(self);
-        if self.order.is_none() {
-            frontmatter.weight = weight;
-        }
-
-        let mut file = File::create(path.join("_index.md"))?;
-        file.write_all(
-            format!(
-                r#"+++
-{}
-+++
-"#,
-                toml::to_string(&frontmatter).unwrap(),
-            )
-            .as_bytes(),
-        )?;
-
-        for (i, content) in self.content.iter().enumerate() {
-            content.write(root_path, &section_path, i)?;
-        }
-        Ok(())
-    }
-}
-
-impl FrontMatterWriter for ErrorCode {
-    fn write(&self, root_path: &Path, current_path: &Path, weight: usize) -> io::Result<()> {
-        let path = root_path.join(current_path);
-
-        let mut frontmatter = FrontMatterErrorCode::from(self);
-        frontmatter.weight = weight;
-
-        let mut file = File::create(path.join(format!("{}.md", self.code)))?;
-        file.write_all(
-            format!(
-                r#"+++
-{}
-+++
-{}"#,
-                toml::to_string(&frontmatter).unwrap(),
-                self.content
-            )
-            .as_bytes(),
-        )?;
-
-        Ok(())
-    }
+use generate_errors::*;
+use std::path::PathBuf;
+
+use clap::Parser;
+
+/// Generate error reference pages from Bevy engine
+/// for use on the Bevy website.
+#[derive(Parser, Debug)]
+#[command(version, about, long_about = None)]
+struct Args {
+    /// Path to the directory containing the
+    /// error files stored in the
+    /// local Bevy GitHub repo.
+    #[arg(long)]
+    errors_path: PathBuf,
+    /// Path to the folder which the
+    /// errors section should be generated in.
+    #[arg(long)]
+    output_path: PathBuf,
+}
+
+fn main() -> anyhow::Result<()> {
+    let args = Args::parse();
+
+    println!("Writing section index & introduction . . .");
+    write_section(&args.output_path)?;
+    println!("Getting error page contents . . .");
+    let error_page_content = get_error_pages(&args.errors_path)?;
+    println!("Writing error pages content to output path . . .");
+    write_pages(&args.output_path, error_page_content)?;
+
+    println!("All good!");
+    Ok(())
 }