From 4bb90351f6decca1a0c6a2cda2edf23e6be669d3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C8=98tefan=20Talpalaru?= Date: Mon, 15 Feb 2021 08:33:49 +0100 Subject: [PATCH] books: sanity checks and docs (#2320) --- Makefile | 6 ++++++ docs/README.md | 16 ++++++++++++++++ 2 files changed, 22 insertions(+) create mode 100644 docs/README.md diff --git a/Makefile b/Makefile index 0ca98d9db..ad597100b 100644 --- a/Makefile +++ b/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 && \ diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..ba45808c9 --- /dev/null +++ b/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 +``` +