preprocessor strictness change (FuelLabs#1987)

* add toml dependency

* add check for 'strict' env var

* update CI with env var

* Update READMEs

* Wording

.github/workflows/ci.yml

@@ -139,7 +139,7 @@ jobs:
           mdbook-version: "0.4.15"
       - name: Emit logs to tmp.txt, fail if build logs contain 'ERROR'
         run: |
-          mdbook build docs &> tmp.txt
+          MDBOOK_preprocessor__FORC_documenter__STRICT="true" mdbook build docs &> tmp.txt
           if cat tmp.txt | grep 'ERROR'
           then
             rm tmp.txt && exit 1

.github/workflows/gh-pages.yml

@@ -39,7 +39,7 @@ jobs:
         with:
           mdbook-version: '0.4.15'
 
-      - run: mdbook build docs
+      - run: MDBOOK_preprocessor__FORC_documenter__STRICT="true" mdbook build docs
 
       - name: Deploy latest
         uses: peaceiris/actions-gh-pages@v3

docs/README.md

@@ -32,6 +32,12 @@ To build book:
 mdbook build
 ```
 
+To build the book on strict mode to check if pages should be removed or added within the Forc Reference:
+
+```sh
+MDBOOK_preprocessor__FORC_documenter__STRICT="true" mdbook build docs
+```
+
 To serve locally:
 
 ```sh

scripts/mdbook-forc-documenter/Cargo.toml

@@ -19,4 +19,5 @@ clap = { version = "3.1", features = [ "derive" ]  }
 mdbook = { version = "0.4", default-features = false }
 semver = "1.0"
 serde = "1.0"
-serde_json = "1.0"
+serde_json = "1.0"
+toml = "0.5"

scripts/mdbook-forc-documenter/README.md

@@ -8,6 +8,12 @@ This preprocessor is automatically run on every build, as long as the `book.toml
 [preprocessor.forc-documenter]
 ```
 
+The preprocessor runs with strict mode **off** by default to enable building the book regardless of errors in the Forc Reference pages. To check if pages should be added or removed, run with the `strict` [environment variable](https://rust-lang.github.io/mdBook/format/configuration/environment-variables.html):
+
+```sh
+MDBOOK_preprocessor__FORC_documenter__STRICT="true" mdbook build docs
+```
+
 ## Usage
 
 ### Adding a new forc command

scripts/mdbook-forc-documenter/src/lib.rs

@@ -11,6 +11,7 @@ use plugins::plugin_commands;
 use std::collections::HashMap;
 use std::fs;
 use std::path::PathBuf;
+use toml::Value;
 
 mod commands;
 mod formatter;
@@ -30,7 +31,14 @@ impl Preprocessor for ForcDocumenter {
         "forc-documenter"
     }
 
-    fn run(&self, _ctx: &PreprocessorContext, mut book: Book) -> Result<Book, Error> {
+    fn run(&self, ctx: &PreprocessorContext, mut book: Book) -> Result<Book, Error> {
+        let strict = ctx
+            .config
+            .get_preprocessor(self.name())
+            .and_then(|t| t.get("strict"))
+            .and_then(Value::as_bool)
+            .unwrap_or(false);
+
         let possible_commands: Vec<String> = possible_forc_commands();
         let examples: HashMap<String, String> = load_examples()?;
 
@@ -85,9 +93,14 @@ impl Preprocessor for ForcDocumenter {
             error_message.push_str(&dangling_chapters_msg(&removed_commands));
         };
 
-        if !error_message.is_empty() {
+        if strict && !error_message.is_empty() {
             Err(Error::msg(error_message))
         } else {
+            if !error_message.is_empty() {
+                eprintln!("Warning:");
+                eprintln!("{}", error_message);
+                eprintln!("The book built successfully - if the changes above were intended or if you are editing pages unrelated to Forc, you may ignore this message.");
+            }
             Ok(book)
         }
     }