installable builds: Fail when building man pages fails

This is unfortunately necessary, because otherwise it would not rerun
the build script just because you installed sphinx.

Because we use the man pages for --help output, they're pretty
necessary.

To override it, you can set $FISH_BUILD_DOCS=0, like

```fish
FISH_BUILD_DOCS=0 cargo install --path .
```

README.rst

@@ -176,9 +176,7 @@ and you can unpack them to ~/.local/share/fish/install/ (currently, subject to c
 
 You will have to use ``--install`` once per user and you will have to run it again when you upgrade fish. It will tell you to.
 
-To install fish as self-installable, just use ``cargo``, like:
-
-.. code:: bash
+To install fish as self-installable, just use ``cargo``, like::
 
    cargo install --path /path/to/fish # if you have a git clone
    cargo install --git https://github.com/fish-shell/fish-shell --tag 4.0 # to build from git once 4.0 is released
@@ -188,6 +186,10 @@ This will place the binaries in ``~/.cargo/bin/``, but you can place them wherev
 
 This build won't have the HTML docs (``help`` will open the online version) or translations.
 
+It requires sphinx by default, if sphinx-build is not available you can build without man pages by running it with $FISH_BUILD_DOCS set to 0::
+
+  FISH_BUILD_DOCS=0 cargo install --path .
+
 You can also link it statically (but not against glibc) and move it to other computers.
 
 Contributing Changes to the Code

build.rs

@@ -362,22 +362,43 @@ fn build_man(build_dir: &Path) {
     ];
     let _ = std::fs::create_dir_all(sec1dir.to_str().unwrap());
 
-    match Command::new("sphinx-build").args(args).output() {
+    rsconf::rebuild_if_env_changed("FISH_BUILD_DOCS");
+    if env::var("FISH_BUILD_DOCS") == Ok("0".to_string()) {
+        println!("cargo:warning=Skipping man pages because $FISH_BUILD_DOCS is set to 0");
+        return;
+    }
+
+    // We run sphinx to build the man pages.
+    // Every error here is fatal so cargo doesn't cache the result
+    // - if we skipped the docs with sphinx not installed, installing it would not then build the docs.
+    // That means you need to explicitly set $FISH_BUILD_DOCS=0 (`FISH_BUILD_DOCS=0 cargo install --path .`),
+    // which is unfortunate - but the docs are pretty important because they're also used for --help.
+    match Command::new("sphinx-build").args(args).spawn() {
+        Err(x) if x.kind() == std::io::ErrorKind::NotFound => {
+            panic!("Could not find sphinx-build to build man pages.\nInstall sphinx or disable building the docs by setting $FISH_BUILD_DOCS=0.");
+        }
         Err(x) => {
-            println!("cargo:warning=Could not build man pages: {:?}", x);
-        }
-        Ok(x) => {
-            if !x.status.success() {
-                println!(
-                    "cargo:warning=Could not build man pages: {:?}",
-                    std::str::from_utf8(&x.stdout).unwrap()
+            // Another error - permissions wrong etc
+            panic!(
+                "Error starting sphinx-build to build man pages: {:?}",
+                x
             );
-                println!(
-                    "cargo:warning=Could not build man pages: {:?}",
-                    std::str::from_utf8(&x.stderr).unwrap()
+        }
+        Ok(mut x) => match x.wait() {
+            Err(err) => {
+                panic!(
+                    "Error waiting for sphinx-build to build man pages: {:?}",
+                    err
                 );
-                panic!("Building docs failed");
+            }
+            Ok(out) => {
+                if out.success() {
+                    // Success!
+                    return;
+                } else {
+                    panic!("sphinx-build failed to build the man pages.");
                 }
             }
+        },
     }
 }