From 423e35c7b72352db6c6b7d6c54ae881a1e2479c7 Mon Sep 17 00:00:00 2001
From: Aliaksandr Valialkin <valyala@victoriametrics.com>
Date: Thu, 25 Jul 2024 13:12:01 +0200
Subject: [PATCH] docs/Makefile: simplify and document `make docs-debug` after
 ce4cc4cbb2c0799c07f64552bab916d40c1d02d1

- Document `make docs-debug` command at https://docs.victoriametrics.com/#documentation

- Remove unneeded ROOTDIR, REPODIR and WORKDIR env vars from docs/Makefile ,
  since it is documented and expected that all the Makefile commands are run from the repository root.

- Use `docker --rm` for running Docker container with local docs server, so it is automatically
  removed after pressing `Ctrl+C`. This makes the container cleanup automatic.

Updates https://github.com/VictoriaMetrics/VictoriaMetrics/pull/6677
---
 README.md     |  7 ++++++-
 docs/Makefile | 23 +++++++++--------------
 2 files changed, 15 insertions(+), 15 deletions(-)

diff --git a/README.md b/README.md
index 3d468c032..9f514c027 100644
--- a/README.md
+++ b/README.md
@@ -2641,7 +2641,9 @@ Report bugs and propose new features [here](https://github.com/VictoriaMetrics/V
 VictoriaMetrics documentation is available at [https://docs.victoriametrics.com/](https://docs.victoriametrics.com/).
 It is built from `*.md` files located in [docs](https://github.com/VictoriaMetrics/VictoriaMetrics/tree/master/docs) folder
 and gets automatically updated once changes are merged to [master](https://github.com/VictoriaMetrics/VictoriaMetrics/tree/master) branch.
+
 To update the documentation follow the steps below:
+
 - [Fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks) 
   VictoriaMetrics repo and apply changes to the docs:
   - To update [the main page](https://docs.victoriametrics.com/) modify [this file](https://github.com/VictoriaMetrics/VictoriaMetrics/blob/master/README.md).
@@ -2653,10 +2655,13 @@ To update the documentation follow the steps below:
   make docs-sync
   ```
 
+- Verify the changes locally by running `make docs-debug`. This command starts locally available docs server at `http://localhost:1313`.
+  Press `Ctrl+C` in the console window were the `make docs-debug` command runs after verifying the changes in docs at `http://localhost:1313`.
+
 - Create [a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request)
   with proposed changes and wait for it to be merged.
 
-Requirements for changes to docs:
+### Requirements for changes in docs
 
 - Keep backward compatibility of existing links. Avoid changing anchors or deleting pages as they could have been
   used or posted in other docs, GitHub issues, stackoverlow answers, etc.
diff --git a/docs/Makefile b/docs/Makefile
index 577974ebd..0de30de22 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -1,7 +1,3 @@
-ROOTDIR := $(dir $(realpath $(lastword $(MAKEFILE_LIST))))
-REPODIR := $(ROOTDIR)/..
-WORKDIR := $(REPODIR)/..
-
 # These commands must be run from the VictoriaMetrics repository root
 
 # Converts images at docs folder to webp format
@@ -20,19 +16,18 @@ docs-images-to-webp-by-extension:
 	find docs/ -type f ! -path 'docs/operator/*' ! -path 'docs/_site/*' -name '*.$(IMAGES_EXTENSION)' -print0 | xargs -0 rm -f
 
 docs-debug:
-	if [ ! -d $(WORKDIR)/vmdocs ]; then \
-		git clone git@github.com:VictoriaMetrics/vmdocs $(WORKDIR)/vmdocs; \
+	if [ ! -d vmdocs ]; then \
+		git clone --depth 1 git@github.com:VictoriaMetrics/vmdocs vmdocs; \
 	fi; \
-	cd $(WORKDIR)/vmdocs && \
+	cd vmdocs && \
 	git checkout main && \
 	git pull origin main && \
-	cd $(REPODIR) && \
+	cd .. && \
 	docker build \
-		-t vmdocs \
-		$(WORKDIR)/vmdocs && \
-	docker rm -f vmdocs || true && \
+		-t vmdocs-docker-package \
+		vmdocs && \
 	docker run \
-		-d \
-		--name vmdocs \
+		--rm \
+		--name vmdocs-docker-container \
 		-p 1313:1313 \
-		-v ./docs:/opt/docs/content vmdocs
+		-v ./docs:/opt/docs/content vmdocs-docker-package