-
Notifications
You must be signed in to change notification settings - Fork 58
/
gen-docs.janet
156 lines (134 loc) · 4.77 KB
/
gen-docs.janet
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
# Generate documentation
(import mendoza/markup-env :as mdz)
(defn- remove-extra-spaces
"Many docstrings have extra spaces that don't look
good when formatted. This removes them."
[str]
(var ret str)
(for i 0 10
(set ret (string/replace " " " " ret)))
ret)
(def- replacer (peg/compile ~(% (any (+ (/ '(set "/*%") ,|(string "_" (0 $))) '1)))))
(defn- sym-to-filename
"Convert a symbol to a filename. Certain filenames are not allowed on various operating systems."
[fname]
(string "examples/" ((peg/match replacer fname) 0) ".janet"))
(defn- check-example
"Check if a binding has related examples. If so, load them
and get their content."
[sym]
(def path (sym-to-filename sym))
(when (= :file (os/stat path :mode))
(def src (slurp path))
src))
(def- url-repl-chars
{(chr "%") "%25"
(chr "?") "_q"
(chr "=") "%3d"})
(defn jdoc-escape
[str]
(def ret @"")
(when-let [prefix (dyn :jdoc-prefix)]
(buffer/push ret prefix))
(each b str
(if-let [repl (in url-repl-chars b)]
(buffer/push-string ret repl)
(buffer/push-byte ret b)))
ret)
(def- ver janet/build)
(def- installed-files-dir (string (os/cwd) "/build"))
(defn- clean-source-file
[path]
(if (string/has-prefix? "/" path)
(string/slice path (length installed-files-dir))
path))
(defn- get-pkg-version
[pkg-name]
(let [info (-> (string "build/.manifests/" pkg-name ".jdn") slurp parse)]
(assert info)
(assert (get info :tag))))
(def spork-version (get-pkg-version "spork"))
(def jpm-version (get-pkg-version "jpm"))
(defn github-source-linker
"Get source code link for a given library (github)"
[library commitish file line]
(string "https://github.com/" library "/blob/" commitish "/" (clean-source-file file) "#L" line))
(defn janet-source-linker
"Source code link for the functions in the janet interpreter"
[file line]
(string "https://github.com/janet-lang/janet/blob/" ver "/"
(if (= "boot.janet" file) "src/boot/boot.janet" file) "#L" line))
(defn- emit-item
"Generate documentation for one entry."
[key env-entry]
(let [{:macro macro
:value val
:ref ref
:source-map sm
:doc docstring} env-entry
binding-type (cond
macro :macro
ref (string :var " (" (type (get ref 0)) ")")
(type val))
docstring (remove-extra-spaces docstring)
source-linker (dyn :source-linker janet-source-linker)
example (check-example key)]
{:tag "div" "class" "binding"
:content [{:tag "span" "class" "binding-sym" "id" key :content key} " "
{:tag "span" "class" "binding-type" :content binding-type} " "
;(if sm [{:tag "span" "class" "binding-type"
:content {:tag "a"
"href" (source-linker (sm 0) (sm 1))
:content "source"}}] []) " "
{:tag "pre" "class" "binding-text" :content (or docstring "")}
;(if example [{:tag "div" "class" "example-title" :content "EXAMPLES"}
{:tag "pre" "class" "mendoza-codeblock"
:content {:tag "code" :language (require "janet.syntax") :content (string example)}}] [])
{:tag "a" "href" (string "https://janetdocs.com/" (jdoc-escape key)) :content "Community Examples"}]}))
(defn- all-entries
[&opt env]
(default env root-env)
(sort (pairs env)))
(defn- get-from-prefix
"Get all bindings that start with a prefix."
[prefix &opt env]
(seq [x :in (all-entries env)
:let [[k entry] x]
:when (symbol? k)
:when (get entry :doc)
:when (not (get entry :private))
:when (string/has-prefix? prefix k)]
x))
(defn- get-from-peg
"Get all bindings that start with a prefix."
[peg &opt env]
(seq [x :in (all-entries env)
:let [[k entry] x]
:when (symbol? k)
:when (get entry :doc)
:when (not (get entry :private))
:when (peg/match peg (string k))]
x))
(defn gen-peg
"Generate the document for all of the core api whose name matches the peg."
[peg &opt env]
(def entries (get-from-peg peg env))
(def index
(seq [[k entry] :in entries]
[{:tag "a" "href" (string "#" k) :content k} " "]))
(def bindings
(seq [[k entry] :in entries]
[{:tag "hr" :no-close true} (emit-item k entry)]))
[{:tag "p" :content index} bindings])
(defn gen-prefix
"Generate the documentation for some subset of the core api."
[prefix &opt env]
(gen-peg (peg/compile prefix) env))
(defn gen-prefix-current
"Generate the documentation for some module in that has been loaded"
[prefix]
(gen-peg (peg/compile prefix) (curenv)))
(defn gen
"Generate all bindings."
[]
(gen-prefix ""))