From fd7b1bd0408707999fde94596d4263398afaa505 Mon Sep 17 00:00:00 2001
From: Jordan Hrycaj <jordan@status.im>
Date: Mon, 12 Apr 2021 16:36:00 +0100
Subject: [PATCH] update doc generator

why:
  generally, there is no role for libbacktrace when docs are generated

  for vm2, undo settings of config.nim and provide the "kludge" flag, so
  circular import/include dependencies can be taken care of (not only)
  for generating docs
---
 nimbus/makefile       | 22 +++++++++++++++-------
 nimbus/vm2/nimdoc.cfg |  8 ++++++++
 2 files changed, 23 insertions(+), 7 deletions(-)
 create mode 100644 nimbus/vm2/nimdoc.cfg

diff --git a/nimbus/makefile b/nimbus/makefile
index 13501d76d..5f3e7b3e1 100644
--- a/nimbus/makefile
+++ b/nimbus/makefile
@@ -39,13 +39,18 @@ endif
 # Compat version is used with external NIM compiler
 NIM_COMPAT := --useVersion:1.2
 
-# Name of NIM compiler, test for newer version on host OS
+# Name of NIMDOC compiler, test for newer version on host OS
 NIM_CMD    := nim
 NIM_TEST   := $(NIM_CMD) $(NIM_COMPAT) --help >/dev/null 2>&1
 NIM_SELECT := $(NIM_TEST) && echo "$(NIM_CMD) $(NIM_COMPAT)"|| echo "$(NIM_CMD)"
 # Note that the back ticks are needed in the following assignment
 NIM_EXE    := `$(NIM_SELECT)`
 
+# Extra nimdoc flags
+NIMDOC_FLAGS := --verbosity:0 --hints:off --warnings:off
+NIMDOC_FLAGS += -d:debug -d:disable_libbacktrace
+NIMDOC_FLAGS += $(NIMFLAGS)
+
 # Markdown compiler (test for discount tool with tables support)
 MD_CMD     := markdown
 MD_TEST    := $(MD_CMD) -VV 2>/dev/null|grep -q TABLES
@@ -63,6 +68,7 @@ help::
 	echo
 	echo "<option>: V=1          -- verbose mode"
 	echo "          X=0          -- preferring local nim compiler (this repo)"
+	echo "          NIMFLAGS=..  -- additional flags for nim-docs generator"
 	echo
 	echo "<target>: docs         -- build NIM docs"
 	echo "          docs-update  -- process missing doc pages"
@@ -80,16 +86,17 @@ help::
 # Build indexed dox
 # ------------------------------------------------------------------------------
 
-# Automatc rule for updating single html/idx file
+# Automatic rule for updating single html/idx file
 docs/%.html : %.nim
 #	use compat option if it works with the nim compiler
 	@mkdir -p docs
 	@nim=$(NIM_EXE); doc_root="$(DOC_ROOT)"; \
+	export NIMBLE_DIR=$(NIMBLE_DIR); \
 	(set -x; $$nim doc --outdir:docs --docRoot:"$$doc_root" --index:on \
-		--errorMax:0 --verbosity:0 --hints:off --warnings:off \
+		--errorMax:0 $(NIMDOC_FLAGS) \
 		"$<" $(MUFFLE)) || true
 
-# Automatc rule for updating markdown files
+# Automatic rule for updating markdown files
 docs/ex/%.html : %.md
 	@mkdir -p $(dir $@)
 	@if $(MD_TEST); then \
@@ -98,7 +105,7 @@ docs/ex/%.html : %.md
 	  (echo "<pre>";(set -x;cat "$<");echo "</pre>"); \
 	fi > "$@"
 
-# Automatc rule for collecting raw files
+# Automatic rule for collecting raw files
 docs/ex/%.png : %.png
 	@mkdir -p $(dir $@)
 	@set -x; cp "$<" "$@"
@@ -165,8 +172,9 @@ docs:: docs-index
 .SILENT: clean-exe
 clean-exe:
 	for f in $(EXE_FILES); do \
-	  [ -f "$$f" ] || continue ;\
-	  (set -x; rm -f "$$f"); \
+	  if   [ -f "$$f"     ]; then (set -x; rm -f "$$f"); \
+	  elif [ -f "$$f.out" ]; then (set -x; rm -f "$$f.out"); \
+	  fi ; \
 	done
 
 .SILENT: clean-docs
diff --git a/nimbus/vm2/nimdoc.cfg b/nimbus/vm2/nimdoc.cfg
new file mode 100644
index 000000000..df141c1a4
--- /dev/null
+++ b/nimbus/vm2/nimdoc.cfg
@@ -0,0 +1,8 @@
+# breaks circular import/include dependencies
+-d:kludge:2
+
+# undo settings from config.nim
+-u:nimStackTraceOverride
+-u:metrics
+--excessiveStackTrace:off
+--threads:off