Migrate docs to mkdocs (#3900)

`mkdocs` works with markdown similar to `mdbook` but is generally more
pleasing to the eye and has several nice UX features.

This PR does the bulk of the transition - likely, a followup would be
needed to fully make use of the extra features and navigation.

Book pages have been kept url-compatible, meaning that for the most
part, old links should continue to work!

Co-authored-by: Etan Kissling <[email protected]>

Author: arnetheduck

Makefile

@@ -658,14 +658,13 @@ libnfuzz.a: | build deps
 		[[ -e "$@" ]] && mv "$@" build/ || true # workaround for https://github.com/nim-lang/Nim/issues/12745
 
 book:
+	"$(MAKE)" -C docs book
+
+auditors-book:
 	[[ "$$(mdbook --version)" = "mdbook v0.4.18" ]] || { echo "'mdbook v0.4.18' not found in PATH. See 'docs/README.md'. Aborting."; exit 1; }
 	[[ "$$(mdbook-toc --version)" == "mdbook-toc 0.8.0" ]] || { echo "'mdbook-toc 0.8.0' not found in PATH. See 'docs/README.md'. Aborting."; exit 1; }
 	[[ "$$(mdbook-open-on-gh --version)" == "mdbook-open-on-gh 2.1.0" ]] || { echo "'mdbook-open-on-gh 2.1.0' not found in PATH. See 'docs/README.md'. Aborting."; exit 1; }
 	[[ "$$(mdbook-admonish --version)" == "mdbook-admonish 1.7.0" ]] || { echo "'mdbook-open-on-gh 1.7.0' not found in PATH. See 'docs/README.md'. Aborting."; exit 1; }
-	cd docs/the_nimbus_book && \
-	mdbook build
-
-auditors-book:
 	cd docs/the_auditors_handbook && \
 	mdbook build
 
@@ -680,7 +679,7 @@ publish-book: | book auditors-book
 	rm -rf tmp-book/* && \
 	mkdir -p tmp-book/auditors-book && \
 	cp -a docs/the_nimbus_book/CNAME tmp-book/ && \
-	cp -a docs/the_nimbus_book/book/* tmp-book/ && \
+	cp -a docs/the_nimbus_book/site/* tmp-book/ && \
 	cp -a docs/the_auditors_handbook/book/* tmp-book/auditors-book/ && \
 	cd tmp-book && \
 	git add . && { \

docs/.gitignore

@@ -0,0 +1 @@
+mkdocs

docs/Makefile

@@ -0,0 +1,17 @@
+mkdocs: mkdocs/bin/mkdocs
+
+mkdocs/bin/mkdocs:
+	test -d mkdocs || python -m venv mkdocs
+	. mkdocs/bin/activate; pip install -r requirements.txt
+
+compile:
+	. mkdocs/bin/activate; pip-compile requirements.in
+
+sync:
+	. mkdocs/bin/activate; pip-sync requirements.txt
+
+serve: mkdocs
+	. mkdocs/bin/activate; cd the_nimbus_book; mkdocs serve
+
+book: mkdocs
+	. mkdocs/bin/activate; cd the_nimbus_book; mkdocs build

docs/requirements.in

@@ -0,0 +1,2 @@
+pip-tools
+mkdocs-material

docs/requirements.txt

@@ -0,0 +1,73 @@
+#
+# This file is autogenerated by pip-compile with python 3.10
+# To update, run:
+#
+#    pip-compile requirements.in
+#
+build==0.8.0
+    # via pip-tools
+click==8.1.3
+    # via
+    #   mkdocs
+    #   pip-tools
+ghp-import==2.1.0
+    # via mkdocs
+importlib-metadata==4.12.0
+    # via mkdocs
+jinja2==3.1.2
+    # via
+    #   mkdocs
+    #   mkdocs-material
+markdown==3.3.7
+    # via
+    #   mkdocs
+    #   mkdocs-material
+    #   pymdown-extensions
+markupsafe==2.1.1
+    # via jinja2
+mergedeep==1.3.4
+    # via mkdocs
+mkdocs==1.3.1
+    # via mkdocs-material
+mkdocs-material==8.3.9
+    # via -r requirements.in
+mkdocs-material-extensions==1.0.3
+    # via mkdocs-material
+packaging==21.3
+    # via
+    #   build
+    #   mkdocs
+pep517==0.12.0
+    # via build
+pip-tools==6.8.0
+    # via -r requirements.in
+pygments==2.12.0
+    # via mkdocs-material
+pymdown-extensions==9.5
+    # via mkdocs-material
+pyparsing==3.0.9
+    # via packaging
+python-dateutil==2.8.2
+    # via ghp-import
+pyyaml==6.0
+    # via
+    #   mkdocs
+    #   pyyaml-env-tag
+pyyaml-env-tag==0.1
+    # via mkdocs
+six==1.16.0
+    # via python-dateutil
+tomli==2.0.1
+    # via
+    #   build
+    #   pep517
+watchdog==2.1.9
+    # via mkdocs
+wheel==0.37.1
+    # via pip-tools
+zipp==3.8.1
+    # via importlib-metadata
+
+# The following packages are considered to be unsafe in a requirements file:
+# pip
+# setuptools

docs/the_nimbus_book/.gitignore

@@ -1 +1,2 @@
 book
+site