Sanitize Makefile and improve document for mdbook

pierrecregut · Feb 16, 2022 · 6223c3f · 6223c3f
1 parent 5cc8a9d
commit 6223c3f
Show file tree

Hide file tree

Showing 4 changed files with 21 additions and 25 deletions.
diff --git a/Makefile b/Makefile
@@ -1,9 +1,8 @@
-MDBOOK_VERSION ?= 0.4.15
 MDBOOK_BIN_VERSION ?= v0.4.15
 SOURCE_PATH := docs/user-guide
 CONTAINER_RUNTIME ?= sudo docker
 IMAGE_NAME := quay.io/metal3-io/mdbook
-IMAGE_VERSION ?= latest
+IMAGE_TAG ?= latest
 HOST_PORT ?= 3000
 BIN_DIR := hack
 MDBOOK_BIN := $(BIN_DIR)/mdbook
@@ -28,17 +27,12 @@ netlify-build: $(MDBOOK_BIN) # Build the user guide
 ## Documentation tooling for local dev
 ## ------------------------------------
 
-.PHONY: container-image
-container-image: # Build mdbook local container image
-	$(CONTAINER_RUNTIME) build --build-arg MDBOOK_VERSION=$(MDBOOK_VERSION) \
-	./docs/ -t $(IMAGE_NAME):$(IMAGE_VERSION)
-
 .PHONY: build
 build: # Build the user guide
 	$(CONTAINER_RUNTIME) run \
 	--rm -it --name metal3 \
 	-v "$$(pwd):/workdir" \
-	$(IMAGE_NAME):$(IMAGE_VERSION) \
+	$(IMAGE_NAME):$(IMAGE_TAG) \
 	mdbook build $(SOURCE_PATH)
 
 .PHONY: serve
@@ -47,13 +41,13 @@ serve: # Serve the user-guide on localhost:3000 (by default)
 	--rm -it --init --name metal3 \
 	-v "$$(pwd):/workdir" \
 	-p $(HOST_PORT):3000 \
-	$(IMAGE_NAME):$(IMAGE_VERSION) \
+	$(IMAGE_NAME):$(IMAGE_TAG) \
 	mdbook serve --open $(SOURCE_PATH) -p 3000 -n 0.0.0.0
 
 .PHONY: clean
 clean: # Clean mdbook generated content
 	$(CONTAINER_RUNTIME) run \
 	--rm -it --name metal3 \
 	-v "$$(pwd):/workdir" \
-	$(IMAGE_NAME):$(IMAGE_VERSION) \
+	$(IMAGE_NAME):$(IMAGE_TAG) \
 	mdbook clean $(SOURCE_PATH)
diff --git a/docs/Dockerfile b/docs/Dockerfile
@@ -1,5 +1,5 @@
 FROM rust:1-slim
-ARG MDBOOK_VERSION="0.4.15"
-RUN cargo install mdbook --vers ${MDBOOK_VERSION}
+ARG MDBOOK_BIN_VERSION="0.4.15"
+RUN cargo install mdbook --vers ${MDBOOK_BIN_VERSION}
 RUN cp /usr/local/cargo/bin/mdbook /usr/bin/mdbook
 WORKDIR /workdir
diff --git a/docs/instructions.md → docs/README.md b/docs/instructions.md → docs/README.md
@@ -10,12 +10,20 @@ Below is the concatenated file structure for the Metal³ user-guide.
 
 ```shell
 ├── book.toml
+├── README.md
 ├── src
-│   ├── images
-│   │   └── metal3-color.svg
-│   ├── introduction.md
-│   ├── project-overview.md
-│   └── SUMMARY.md
+│   ├── bmo
+│   │   └── OWNERS
+│   ├── capm3
+│   │   └── OWNERS
+│   ├── images
+│   │   └── metal3-color.svg
+│   ├── introduction.md
+│   ├── ipam
+│   │   └── OWNERS
+│   ├── ironic
+│   │   └── OWNERS
+│   └── SUMMARY.md
 └── theme
     └── favicon.svg
 ```
@@ -63,10 +71,4 @@ All the commands below are executed within mdbook container.
 
     ```bash
     $ make clean
-    ```
-
-1. Build mdbook container image locally.
-
-    ```bash
-    $ make container-image
-    ```
+    ```
diff --git a/docs/user-guide/README.md b/docs/user-guide/README.md
@@ -43,11 +43,11 @@ Our Netlify configuration is in the [netlify.toml](https://github.com/metal3-io/
 All the configurations of the mdbook, such as content path, version, from where to get the binary while building the user-guide is defined in the [Makefile](https://github.com/metal3-io/metal3-docs/blob/main/Makefile).
 
 ```sh
-MDBOOK_VERSION ?= latest
 MDBOOK_BIN_VERSION ?= v0.4.15
 SOURCE_PATH := docs/user-guide
 CONTAINER_RUNTIME ?= sudo docker
 IMAGE_NAME := quay.io/metal3-io/mdbook
+IMAGE_TAG ?= latest
 HOST_PORT ?= 3000
 BIN_DIR := hack
 MDBOOK_BIN := $(BIN_DIR)/mdbook