Merge pull request #568 from status-im/feature/nim-docs-generation-for-nimbus2
generate docs (and other niceties ..) for nimbus sub-directory
This commit is contained in:
commit
e5de7eec22
|
@ -1,4 +1,4 @@
|
|||
/nimcache
|
||||
*~
|
||||
|
||||
# Executables shall be put in an ignored build/ directory
|
||||
/build
|
||||
|
@ -20,6 +20,15 @@
|
|||
*.exe
|
||||
*.dll
|
||||
|
||||
# Ignore generated C and doc files
|
||||
nimcache
|
||||
/nimbus/docs
|
||||
|
||||
# Ignore test reports
|
||||
VMTests.md
|
||||
/newBlock[Cc]hainTests.md
|
||||
/witnessBuilderBC.md
|
||||
/witnessBuilderGST.md
|
||||
|
||||
/debug*.json
|
||||
/block*.json
|
||||
|
|
File diff suppressed because it is too large
Load Diff
|
@ -0,0 +1,218 @@
|
|||
#! /usr/bin/make -f
|
||||
|
||||
SAVED_PATH := $(PATH)
|
||||
PWD := $(shell pwd)
|
||||
|
||||
ifeq ($(MSYSTEM),MINGW32)
|
||||
# Under MinGW, the NIM doc compiler wants absolute pathname arguments
|
||||
# looking like C:\\MinGW\\msys\\1.0\\home ...
|
||||
DOC_ROOT := `pwd -W|sed 's|/|\\\\\\\\|g'`
|
||||
else
|
||||
DOC_ROOT := $(PWD)
|
||||
endif
|
||||
|
||||
# Collect document names
|
||||
SFX_FILTER := sed -e 's|^\./||;/\/\./d;/^docs\//d;s/\.[a-z]*$$//'
|
||||
PNG_FILES := $(shell find . -name '*.png' -print|$(SFX_FILTER))
|
||||
MD_FILES := $(shell find . -name '*.md' -print|$(SFX_FILTER))
|
||||
EXE_FILES := $(shell find . -name '*.nim' -print|$(SFX_FILTER))
|
||||
|
||||
# Needed for the NIM compiler that comes with this repo
|
||||
NIMBLE_DIR := $(dir $(PWD))/vendor/.nimble
|
||||
NIM_PATH := $(dir $(PWD))/vendor/nimbus-build-system/vendor/Nim/bin
|
||||
|
||||
# Support for verbosity: V=1, V=2 etc.
|
||||
ifneq ($(if $V,$V,0),0)
|
||||
MUFFLE :=
|
||||
else
|
||||
MUFFLE := 2>/dev/null
|
||||
endif
|
||||
|
||||
# Support for external NIM compiler unless X=0
|
||||
ifneq ($(if $X,$X,1),0)
|
||||
# works with external nim 1.5.1 (not the local 1.2.10 one)
|
||||
PATH := $(SAVED_PATH):$(NIM_PATH):$(NIMBLE_DIR)/bin
|
||||
else
|
||||
PATH := $(NIM_PATH):$(NIMBLE_DIR)/bin:$(SAVED_PATH)
|
||||
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
|
||||
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)`
|
||||
|
||||
# Markdown compiler (test for discount tool with tables support)
|
||||
MD_CMD := markdown
|
||||
MD_TEST := $(MD_CMD) -VV 2>/dev/null|grep -q TABLES
|
||||
|
||||
# Default target
|
||||
default: help
|
||||
|
||||
# ------------------------------------------------------------------------------
|
||||
# Help page
|
||||
# ------------------------------------------------------------------------------
|
||||
|
||||
.SILENT: help
|
||||
help::
|
||||
echo "Usage: $(MAKE) <target> [<option> ..]"
|
||||
echo
|
||||
echo "<option>: V=1 -- verbose mode"
|
||||
echo " X=0 -- preferring local nim compiler (this repo)"
|
||||
echo
|
||||
echo "<target>: docs -- build NIM docs"
|
||||
echo " docs-update -- process missing doc pages"
|
||||
echo " docs-index -- index collected docs"
|
||||
echo
|
||||
echo " clean -- clean up generated and backup files (not docs)"
|
||||
echo " clean-exe -- clean up generated executables"
|
||||
echo " clean-docs -- clean up generated docs and extra files"
|
||||
echo
|
||||
echo " distclean -- purge unnecessary stuff including docs"
|
||||
echo " clobber -- same as distclean"
|
||||
echo
|
||||
|
||||
# ------------------------------------------------------------------------------
|
||||
# Build indexed dox
|
||||
# ------------------------------------------------------------------------------
|
||||
|
||||
# Automatc 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)"; \
|
||||
(set -x; $$nim doc --outdir:docs --docRoot:"$$doc_root" --index:on \
|
||||
--errorMax:0 --verbosity:0 --hints:off --warnings:off \
|
||||
"$<" $(MUFFLE)) || true
|
||||
|
||||
# Automatc rule for updating markdown files
|
||||
docs/ex/%.html : %.md
|
||||
@mkdir -p $(dir $@)
|
||||
@if $(MD_TEST); then \
|
||||
(set -x; $(MD_CMD) "$<"); \
|
||||
else \
|
||||
(echo "<pre>";(set -x;cat "$<");echo "</pre>"); \
|
||||
fi > "$@"
|
||||
|
||||
# Automatc rule for collecting raw files
|
||||
docs/ex/%.png : %.png
|
||||
@mkdir -p $(dir $@)
|
||||
@set -x; cp "$<" "$@"
|
||||
|
||||
|
||||
.PHONY: docs-index-helper
|
||||
.SILENT: docs-index-helper
|
||||
docs-index-helper:
|
||||
nim=$(NIM_EXE); \
|
||||
$$nim --version | sed q ; set -x ;\
|
||||
$$nim --skipProjCfg buildIndex -o:docs/theindex.html \
|
||||
--verbosity:0 --hints:off --warnings:off docs
|
||||
|
||||
.PHONY: docs-update-helper
|
||||
.SILENT: docs-update-helper
|
||||
docs-update-helper::
|
||||
$(NIM_EXE) --version | sed q
|
||||
|
||||
docs-update-helper:: $(foreach f,$(EXE_FILES),docs/$f.html)
|
||||
|
||||
# Kludge: some docs would only compile with the local NIM compiler
|
||||
ifneq ($(X),0)
|
||||
docs-update-helper::
|
||||
$(MAKE) docs-update-helper X=0 V=$(V)
|
||||
endif
|
||||
|
||||
|
||||
.PHONY: docs-extra-helper
|
||||
.SILENT: docs-extra-helper
|
||||
docs-extra-helper::
|
||||
$(MD_TEST) || ( \
|
||||
echo ;\
|
||||
echo "*** Discount markdown command with table processing is unavailable." ;\
|
||||
echo " On Debian/Ubuntu it is installed via \"apt install discount\".";\
|
||||
echo " So \"make\" is going to fall back to text file wrapping which can" ;\
|
||||
echo " be changed by passing \"MD_TEST=true\" to the \"make\" command line." ;\
|
||||
echo ;\
|
||||
)
|
||||
|
||||
docs-extra-helper:: $(foreach f,$(MD_FILES),docs/ex/$f.html)
|
||||
docs-extra-helper:: $(foreach f,$(PNG_FILES),docs/ex/$f.png)
|
||||
|
||||
|
||||
.PHONY: docs-update
|
||||
.SILENT: docs-update
|
||||
docs-update:: docs-update-helper
|
||||
docs-update:: docs-extra-helper
|
||||
|
||||
.PHONY: docs-index
|
||||
.SILENT: docs-index
|
||||
docs-index:: docs-index-helper
|
||||
|
||||
.PHONY: docs
|
||||
.SILENT: docs
|
||||
docs:: docs-update
|
||||
docs:: docs-index
|
||||
|
||||
# ------------------------------------------------------------------------------
|
||||
# Clean up etc.
|
||||
# ------------------------------------------------------------------------------
|
||||
|
||||
.PHONY: clobber distclean clean clean-exe clean-docs
|
||||
|
||||
.SILENT: clean-exe
|
||||
clean-exe:
|
||||
for f in $(EXE_FILES); do \
|
||||
[ -f "$$f" ] || continue ;\
|
||||
(set -x; rm -f "$$f"); \
|
||||
done
|
||||
|
||||
.SILENT: clean-docs
|
||||
clean-docs:
|
||||
for f in docs/dochack.js docs/nimdoc.out.css; do \
|
||||
[ ! -f "$$f" ] || (set -x; rm -f "$$f"); \
|
||||
done
|
||||
for f in $(foreach f,$(EXE_FILES),docs/$f) \
|
||||
$(foreach f,$(PNG_FILES),docs/ex/$f) \
|
||||
$(foreach f,$(MD_FILES),docs/ex/$f) \
|
||||
docs/theindex; \
|
||||
do \
|
||||
[ ! -f "$$f.html" ] || (set -x; rm -f "$$f.html"); \
|
||||
[ ! -f "$$f.idx" ] || (set -x; rm -f "$$f.idx"); \
|
||||
[ ! -f "$$f.png" ] || (set -x; rm -f "$$f.png"); \
|
||||
done
|
||||
find docs -name 'nimdoc?out.css' -print 2>/dev/null | \
|
||||
while read f_css ; do \
|
||||
[ ! -f "$$f_css" ] || (set -x; rm -f "$$f_css"); \
|
||||
done
|
||||
for d in $(shell find docs -depth -type d -print $(MUFFLE)); do \
|
||||
(set -x; rmdir "$$d" $(MUFFLE)) || true; \
|
||||
done
|
||||
|
||||
.SILENT: clean-bakfiles
|
||||
clean-bakfiles:
|
||||
for f in $(shell find . -type f \
|
||||
-name '*~' -o -name '*.bak' -print); do \
|
||||
(set -x; rm -f "$$f"); \
|
||||
done
|
||||
|
||||
.SILENT: clean-nimcache
|
||||
clean-nimcache:
|
||||
# |while.. is like "|xargs -rn1 rm -rf" but with nicer log message
|
||||
find . -name 'nimcache' -type d -print 2>/dev/null | \
|
||||
while read d; do (set -x; rm -rf "$$d"); done
|
||||
|
||||
clean:: clean-exe
|
||||
clean:: clean-bakfiles
|
||||
clean:: clean-nimcache
|
||||
|
||||
distclean:: clean
|
||||
distclean:: clean-docs
|
||||
|
||||
clobber:: distclean
|
||||
|
||||
# ------------------------------------------------------------------------------
|
||||
# End
|
||||
# ------------------------------------------------------------------------------
|
3725
witnessBuilderBC.md
3725
witnessBuilderBC.md
File diff suppressed because it is too large
Load Diff
2669
witnessBuilderGST.md
2669
witnessBuilderGST.md
File diff suppressed because it is too large
Load Diff
Loading…
Reference in New Issue