books: sanity checks and docs (#2320)

Makefile

@@ -488,6 +488,8 @@ libnfuzz.a: | build deps
 		[[ -e "$@" ]] && mv "$@" build/ || true # workaround for https://github.com/nim-lang/Nim/issues/12745
 
 book:
+	which mdbook &>/dev/null || { echo "'mdbook' not found in PATH. See 'docs/README.md'. Aborting."; exit 1; }
+	which mdbook-toc &>/dev/null || { echo "'mdbook-toc' not found in PATH. See 'docs/README.md'. Aborting."; exit 1; }
 	cd docs/the_nimbus_book && \
 	mdbook build
 
@@ -496,6 +498,10 @@ auditors-book:
 	mdbook build
 
 publish-book: | book auditors-book
+	CURRENT_BRANCH="$$(git rev-parse --abbrev-ref HEAD)"; \
+		if [[ "$${CURRENT_BRANCH}" != "stable" && "$${CURRENT_BRANCH}" != "unstable" ]]; then \
+			echo -e "\nWarning: you're publishing the books from a branch that is neither 'stable' nor 'unstable'!\n"; \
+		fi
 	git branch -D gh-pages && \
 	git branch --track gh-pages origin/gh-pages && \
 	git worktree add tmp-book gh-pages && \

docs/README.md

@@ -0,0 +1,16 @@
+The books in this folder were produced using [mdBook](https://github.com/rust-lang/mdBook) - see installation guide.
+
+Some books also use [mdbook-toc](https://github.com/badboy/mdbook-toc) for tables of contents.
+
+```bash
+# Install or update tooling (make sure you add "~/.cargo/bin" to PATH):
+cargo install mdbook mdbook-toc
+
+# Work on the book locally - open "http://localhost:4000" for live version
+cd docs/the_nimbus_book
+mdbook serve -p 4000
+
+# Publish book using makefile (in top-level)
+make publish-book
+```
+