Fix rendering of table of contents using the local web server (#1043)

* Explicitly set SHELL in docs.mk at requires bash

* Ensure Mimir has an index file for proper table of contents rendering

Without the _index.md file, the table of contents doesn't expand as it
does with the public website.

* Ensure `make docs` can be run from the `/docs` directory

This is consistent with other Grafana labs project. The include in the
top-level Makefile is updated to allow it to also be run from the root
of the repository.

Signed-off-by: Jack Baldry <[email protected]>

Makefile

@@ -590,5 +590,6 @@ packaging/deb/debian-systemd/$(UPTODATE): packaging/deb/debian-systemd/Dockerfil
 test-packages: packages packaging/rpm/centos-systemd/$(UPTODATE) packaging/deb/debian-systemd/$(UPTODATE)
 	./tools/packaging/test-packages $(IMAGE_PREFIX) $(VERSION)
 
-include docs.mk
+include docs/docs.mk
+DOCS_DIR = docs/sources
 docs: doc

docs/Makefile

@@ -0,0 +1,10 @@
+.DEFAULT_GOAL: help
+
+# Adapted from https://www.thapaliya.com/en/writings/well-documented-makefiles/
+.PHONY: help
+help: ## Display this help.
+help:
+	@awk 'BEGIN {FS = ": ##"; printf "Usage:\n  make <target>\n\nTargets:\n"} /^[a-zA-Z0-9_\.\-\/%]+: ##/ { printf "  %-45s %s\n", $$1, $$2 }' $(MAKEFILE_LIST)
+
+include docs.mk
+

docs.mk → docs/docs.mk

@@ -1,6 +1,8 @@
+SHELL = /usr/bin/env bash
+
 DOCS_IMAGE   = grafana/docs-base:latest
 DOCS_PROJECT = mimir
-DOCS_DIR     = docs/sources
+DOCS_DIR     = sources
 
 # This allows ports and base URL to be overridden, so services like ngrok.io can
 # be used to share a local running docs instances.
@@ -20,7 +22,7 @@ define docs_docker_run
 	@echo ""
 	@read -p "Press a key to continue"
 
-	@docker run --name $(DOCS_DOCKER_CONTAINER) $(DOCS_DOCKER_RUN_FLAGS) /bin/bash -c 'find content/docs/ -mindepth 1 -maxdepth 1 -type d -a ! -name "$(DOCS_PROJECT)" -exec rm -rf {} \; && exec $(1)'
+	@docker run --name $(DOCS_DOCKER_CONTAINER) $(DOCS_DOCKER_RUN_FLAGS) /bin/bash -c 'find content/docs/ -mindepth 1 -maxdepth 1 -type d -a ! -name "$(DOCS_PROJECT)" -exec rm -rf {} \; && touch content/docs/mimir/_index.md && exec $(1)'
 endef
 
 .PHONY: docs-docker-rm