From 131ee291903df424ad602b50d1b5328bf5880301 Mon Sep 17 00:00:00 2001 From: Calvin Rose Date: Mon, 17 Dec 2018 01:41:11 -0500 Subject: [PATCH] Add docs target to generate documentation. --- Makefile | 12 ++++++++- doc/gendoc.janet | 62 +++++++++++++++++++++++++-------------------- src/core/core.janet | 16 +++++++++--- src/core/io.c | 2 +- src/core/parse.c | 2 +- 5 files changed, 61 insertions(+), 33 deletions(-) diff --git a/Makefile b/Makefile index 9eeffa93..021cd4d6 100644 --- a/Makefile +++ b/Makefile @@ -159,6 +159,15 @@ build/janet-%.tar.gz: $(JANET_TARGET) src/include/janet/janet.h \ janet.1 LICENSE CONTRIBUTING.md $(JANET_LIBRARY) README.md $(wildcard doc/*) tar -czvf $@ $^ +######################### +##### Documentation ##### +######################### + +docs: build/doc.html + +build/doc.html: $(JANET_TARGET) doc/gendoc.janet + $(JANET_TARGET) doc/gendoc.janet > build/doc.html + ################# ##### Other ##### ################# @@ -183,5 +192,6 @@ uninstall: -rm -rf $(INCLUDEDIR) $(LDCONFIG) -.PHONY: clean install repl debug valgrind test valtest emscripten dist uninstall \ +.PHONY: clean install repl debug valgrind test \ + valtest emscripten dist uninstall docs \ $(TEST_PROGRAM_PHONIES) $(TEST_PROGRAM_VALPHONIES) diff --git a/doc/gendoc.janet b/doc/gendoc.janet index ecfb2b05..9f4ace92 100644 --- a/doc/gendoc.janet +++ b/doc/gendoc.janet @@ -1,20 +1,25 @@ # Generate documentation (def- prelude - ``` - - - - - Janet Language Documentation - - - ```) +``` + + + + +Janet Language Documentation + + + +```) (def- postlude - ``` - - ```) +``` + +```) (def- escapes {10 "
" @@ -43,21 +48,24 @@ (buffer/push-byte buf byte))) buf) -(defn- gen-one - "Generate documentation for a binding. Returns an - html fragment." - [key docstring] - (if-let [index (string/find "\n" docstring)] - (let [first-line (html-escape (string/slice docstring 0 index)) - rest (html-escape (trim-lead (string/slice docstring (inc index))))] - (string "

" first-line "

\n" - "

" rest "

\n")) - (string "

" (html-escape key) "

\n" - "

" (html-escape docstring) "

\n"))) +(defn- emit-item + "Generate documentation for one entry." + [key env-entry] + (let [{:macro macro + :value val + :ref ref + :doc docstring} env-entry + binding-type (cond + macro :macro + ref (string :var " (" (type ref.0) ")") + (type val))] + (string "

" (html-escape key) "

" + "" binding-type "" + "

" (trim-lead (html-escape docstring)) "

"))) # Generate parts and print them to stdout -(def parts (seq [[k {:doc d :private p}] +(def parts (seq [[k entry] :in (sort (pairs (table/getproto _env))) - :when (and d (not p))] - (gen-one k d))) -(print prelude ;parts postlude) + :when (and entry:doc (not entry:private))] + (emit-item k entry))) +(print prelude ;(interpose "
" parts) postlude) diff --git a/src/core/core.janet b/src/core/core.janet index 141a2c84..b5770d2e 100644 --- a/src/core/core.janet +++ b/src/core/core.janet @@ -1074,8 +1074,18 @@ value, one key will be ignored." (if (not x) (print "symbol " sym " not found.") (do + (def bind-type + (string " " + (cond + x:ref (string :var " (" (type (get x:ref 0)) ")") + x:macro :macro + (type x:value)) + "\n")) (def d x:doc) - (print "\n\n" (if d (doc-format d) "no documentation found.") "\n\n")))) + (print "\n\n" + (if d bind-type "") + (if d (doc-format d) "no documentation found.") + "\n\n")))) (defmacro doc "Shows documentation for the given symbol." @@ -1176,15 +1186,15 @@ value, one key will be ignored." ret) (defn all - [pred xs] "Returns true if all xs are truthy, otherwise the first false or nil value." + [pred xs] (var ret true) (loop [x :in xs :while ret] (set ret (pred x))) ret) (defn some - [pred xs] "Returns false if all xs are false or nil, otherwise returns the first true value." + [pred xs] (var ret nil) (loop [x :in xs :while (not ret)] (if-let [y (pred x)] (set ret y))) ret) diff --git a/src/core/io.c b/src/core/io.c index 7fc4edca..7d23e1ba 100644 --- a/src/core/io.c +++ b/src/core/io.c @@ -47,7 +47,7 @@ struct IOFile { static int janet_io_gc(void *p, size_t len); JanetAbstractType janet_io_filetype = { - ":core.file", + ":core/file", janet_io_gc, NULL }; diff --git a/src/core/parse.c b/src/core/parse.c index a1cf7d1f..79f20711 100644 --- a/src/core/parse.c +++ b/src/core/parse.c @@ -609,7 +609,7 @@ static int parsergc(void *p, size_t size) { } static JanetAbstractType janet_parse_parsertype = { - ":core.parser", + ":core/parser", parsergc, parsermark };