vdoc: use maps, enum-based categorization; fixes (#6659)
Ned Palacios
GitHub
parent
0e56b96bda
commit
5b1ab3b0bb
|
|
@ -274,6 +274,9 @@ body {
|
|||
word-break: break-all; /* IE11 */
|
||||
word-break: break-word;
|
||||
}
|
||||
.doc-content > .doc-node.const:nth-child(2) {
|
||||
padding-bottom: 0 !important;
|
||||
}
|
||||
.doc-content > .doc-node.const:not(:first-child) {
|
||||
padding-top: 4rem;
|
||||
}
|
||||
|
|
@ -556,6 +559,9 @@ pre {
|
|||
.doc-nav .content.hidden {
|
||||
display: flex;
|
||||
}
|
||||
.doc-content > .doc-node.const:nth-child(2) {
|
||||
padding-bottom: 0 !important;
|
||||
}
|
||||
.doc-content > .doc-node.const:not(:first-child) {
|
||||
padding-top: 0;
|
||||
}
|
||||
|
|
|
|||
239
cmd/tools/vdoc.v
239
cmd/tools/vdoc.v
|
|
@ -15,6 +15,7 @@ import v.table
|
|||
import v.token
|
||||
import v.vmod
|
||||
import v.pref
|
||||
import json
|
||||
|
||||
enum HighlightTokenTyp {
|
||||
unone
|
||||
|
|
@ -124,10 +125,12 @@ struct ParallelDoc {
|
|||
i int
|
||||
}
|
||||
|
||||
[inline]
|
||||
fn slug(title string) string {
|
||||
return title.replace(' ', '-')
|
||||
}
|
||||
|
||||
[inline]
|
||||
fn open_url(url string) {
|
||||
$if windows {
|
||||
os.system('start $url')
|
||||
|
|
@ -149,7 +152,6 @@ fn (mut cfg DocConfig) serve_html() {
|
|||
exit(1)
|
||||
}
|
||||
def_name := docs.keys()[0]
|
||||
//
|
||||
server_url := 'http://localhost:' + cfg.server_port.str()
|
||||
server := net.listen(cfg.server_port) or {
|
||||
panic(err)
|
||||
|
|
@ -268,7 +270,9 @@ fn js_compress(str string) string {
|
|||
}
|
||||
js.write(trimmed)
|
||||
}
|
||||
return js.str()
|
||||
js_str := js.str()
|
||||
js.free()
|
||||
return js_str
|
||||
}
|
||||
|
||||
fn escape(str string) string {
|
||||
|
|
@ -278,29 +282,9 @@ fn escape(str string) string {
|
|||
fn (cfg DocConfig) gen_json(idx int) string {
|
||||
dcs := cfg.docs[idx]
|
||||
mut jw := strings.new_builder(200)
|
||||
jw.write('{"module_name":"$dcs.head.name","description":"${escape(dcs.head.comment)}","contents":[')
|
||||
for i, cn in dcs.contents {
|
||||
name := cn.name.all_after(dcs.head.name)
|
||||
jw.write('{"name":"$name","signature":"${escape(cn.content)}",')
|
||||
jw.write('"description":"${escape(cn.comment)}",')
|
||||
jw.write('"position":[$cn.pos.line,$cn.pos.col,$cn.pos.len],')
|
||||
jw.write('"file_path":"$cn.file_path",')
|
||||
jw.write('"attrs":{')
|
||||
mut j := 0
|
||||
for n, v in cn.attrs {
|
||||
jw.write('"$n":"$v"')
|
||||
if j < cn.attrs.len - 1 {
|
||||
jw.write(',')
|
||||
}
|
||||
j++
|
||||
}
|
||||
jw.write('}')
|
||||
jw.write('}')
|
||||
if i < dcs.contents.len - 1 {
|
||||
jw.write(',')
|
||||
}
|
||||
}
|
||||
jw.write('],"generator":"vdoc","time_generated":"$dcs.time_generated.str()"}')
|
||||
jw.write('{"module_name":"$dcs.head.name","description":"${escape(dcs.head.comment)}","contents":')
|
||||
jw.write(json.encode(dcs.contents.keys().map(dcs.contents[it])))
|
||||
jw.write(',"generator":"vdoc","time_generated":"$dcs.time_generated.str()"}')
|
||||
return jw.str()
|
||||
}
|
||||
|
||||
|
|
@ -392,27 +376,27 @@ fn doc_node_html(dd doc.DocNode, link string, head bool, tb &table.Table) string
|
|||
head_tag := if head { 'h1' } else { 'h2' }
|
||||
md_content := markdown.to_html(dd.comment)
|
||||
hlighted_code := html_highlight(dd.content, tb)
|
||||
node_class := if dd.name == 'Constants' { ' const' } else { '' }
|
||||
sym_name := if dd.attrs.exists('parent') && dd.attrs['parent'] !in ['void', '', 'Constants'] { dd.attrs['parent'] +
|
||||
'.' + dd.name } else { dd.name }
|
||||
node_class := if dd.kind == .const_group { ' const' } else { '' }
|
||||
sym_name := if dd.parent_name.len > 0 && dd.parent_name != 'void' { dd.parent_name + '.' + dd.name } else { dd.name }
|
||||
node_id := slug(sym_name)
|
||||
hash_link := if !head { ' <a href="#$node_id">#</a>' } else { '' }
|
||||
dnw.writeln('<section id="$node_id" class="doc-node$node_class">')
|
||||
if dd.name != 'README' && dd.attrs['parent'] != 'Constants' {
|
||||
if dd.name.len > 0 {
|
||||
dnw.write('<div class="title"><$head_tag>$sym_name$hash_link</$head_tag>')
|
||||
if link.len != 0 {
|
||||
dnw.write('<a class="link" rel="noreferrer" target="_blank" href="$link">$link_svg</a>')
|
||||
}
|
||||
dnw.write('</div>')
|
||||
}
|
||||
if head {
|
||||
dnw.write(md_content)
|
||||
} else {
|
||||
if !head && dd.content.len > 0 {
|
||||
dnw.writeln('<pre class="signature"><code>$hlighted_code</code></pre>')
|
||||
dnw.writeln(md_content)
|
||||
}
|
||||
dnw.writeln('</section>')
|
||||
return dnw.str()
|
||||
dnw.writeln('$md_content\n</section>')
|
||||
dnw_str := dnw.str()
|
||||
defer {
|
||||
dnw.free()
|
||||
}
|
||||
return dnw_str
|
||||
}
|
||||
|
||||
fn (cfg DocConfig) readme_idx() int {
|
||||
|
|
@ -426,12 +410,11 @@ fn (cfg DocConfig) readme_idx() int {
|
|||
}
|
||||
|
||||
fn write_toc(cn doc.DocNode, nodes []doc.DocNode, mut toc strings.Builder) {
|
||||
toc_slug := if cn.content.len == 0 { '' } else { slug(cn.name) }
|
||||
toc_slug := if cn.name.len == 0 { '' } else { slug(cn.name) }
|
||||
toc.write('<li class="open"><a href="#$toc_slug">$cn.name</a>')
|
||||
children := nodes.find_children_of(cn.name)
|
||||
if cn.name != 'Constants' {
|
||||
toc.writeln(' <ul>')
|
||||
for child in children {
|
||||
for child in cn.children {
|
||||
cname := cn.name + '.' + child.name
|
||||
toc.writeln('<li><a href="#${slug(cname)}">$child.name</a></li>')
|
||||
}
|
||||
|
|
@ -444,11 +427,10 @@ fn (cfg DocConfig) write_content(cn &doc.DocNode, dcs &doc.Doc, mut hw strings.B
|
|||
base_dir := os.dir(os.real_path(cfg.input_path))
|
||||
file_path_name := if cfg.is_multi { cn.file_path.replace('$base_dir/', '') } else { os.file_name(cn.file_path) }
|
||||
src_link := get_src_link(cfg.manifest.repo_url, file_path_name, cn.pos.line)
|
||||
children := dcs.contents.find_children_of(cn.name)
|
||||
if cn.content.len != 0 {
|
||||
if cn.content.len != 0 || (cn.name == 'Constants') {
|
||||
hw.write(doc_node_html(cn, src_link, false, dcs.table))
|
||||
}
|
||||
for child in children {
|
||||
for child in cn.children {
|
||||
child_file_path_name := child.file_path.replace('$base_dir/', '')
|
||||
child_src_link := get_src_link(cfg.manifest.repo_url, child_file_path_name, child.pos.line)
|
||||
hw.write(doc_node_html(child, child_src_link, false, dcs.table))
|
||||
|
|
@ -456,18 +438,16 @@ fn (cfg DocConfig) write_content(cn &doc.DocNode, dcs &doc.Doc, mut hw strings.B
|
|||
}
|
||||
|
||||
fn (cfg DocConfig) gen_html(idx int) string {
|
||||
dcs := cfg.docs[idx]
|
||||
mut toc := strings.new_builder(200)
|
||||
mut toc2 := strings.new_builder(200)
|
||||
mut symbols_toc := strings.new_builder(200)
|
||||
mut modules_toc := strings.new_builder(200)
|
||||
mut contents := strings.new_builder(200)
|
||||
dcs := cfg.docs[idx]
|
||||
dcs_contents := dcs.contents.arr()
|
||||
// generate toc first
|
||||
contents.writeln(doc_node_html(dcs.head, '', true, dcs.table))
|
||||
for cn in dcs.contents {
|
||||
for cn in dcs_contents {
|
||||
cfg.write_content(&cn, &dcs, mut contents)
|
||||
if cn.attrs['parent'] == 'Constants' || cn.attrs['category'] == 'Methods' {
|
||||
continue
|
||||
}
|
||||
write_toc(cn, dcs.contents, mut toc)
|
||||
write_toc(cn, dcs_contents, mut symbols_toc)
|
||||
} // write head
|
||||
// write css
|
||||
version := if cfg.manifest.version.len != 0 { cfg.manifest.version } else { '' }
|
||||
|
|
@ -481,39 +461,37 @@ fn (cfg DocConfig) gen_html(idx int) string {
|
|||
}
|
||||
names := doc.head.name.split('.')
|
||||
submod_prefix = if names.len > 1 { names[0] } else { doc.head.name }
|
||||
href_name := if ('vlib' in cfg.input_path &&
|
||||
href_name := if (dcs.is_vlib &&
|
||||
doc.head.name == 'builtin' && !cfg.include_readme) ||
|
||||
doc.head.name == 'README' {
|
||||
'./index.html'
|
||||
} else if submod_prefix !in cfg.docs.map(it.head.name) {
|
||||
'#'
|
||||
} else {
|
||||
'./' + doc.head.name + '.html'
|
||||
'./${doc.head.name}.html'
|
||||
}
|
||||
submodules := cfg.docs.filter(it.head.name.starts_with(submod_prefix + '.'))
|
||||
dropdown := if submodules.len > 0 { cfg.assets['arrow_icon'] } else { '' }
|
||||
mut is_submodule_open := false
|
||||
for _, cdoc in submodules {
|
||||
if cdoc.head.name == dcs.head.name {
|
||||
is_submodule_open = true
|
||||
}
|
||||
}
|
||||
active_class := if doc.head.name == dcs.head.name { ' active' } else { '' }
|
||||
toc2.write('<li class="open$active_class"><div class="menu-row">$dropdown<a href="$href_name">$submod_prefix</a></div>')
|
||||
modules_toc.write('<li class="open$active_class"><div class="menu-row">$dropdown<a href="$href_name">$submod_prefix</a></div>')
|
||||
for j, cdoc in submodules {
|
||||
if j == 0 {
|
||||
toc2.write('<ul>')
|
||||
modules_toc.write('<ul>')
|
||||
}
|
||||
submod_name := cdoc.head.name.all_after(submod_prefix + '.')
|
||||
sub_selected_classes := if cdoc.head.name == dcs.head.name { ' class="active"' } else { '' }
|
||||
toc2.write('<li$sub_selected_classes><a href="./${cdoc.head.name}.html">$submod_name</a></li>')
|
||||
modules_toc.write('<li$sub_selected_classes><a href="./${cdoc.head.name}.html">$submod_name</a></li>')
|
||||
if j == submodules.len - 1 {
|
||||
toc2.write('</ul>')
|
||||
modules_toc.write('</ul>')
|
||||
}
|
||||
}
|
||||
toc2.write('</li>')
|
||||
modules_toc.write('</li>')
|
||||
}
|
||||
}
|
||||
modules_toc_str := modules_toc.str()
|
||||
symbols_toc_str := symbols_toc.str()
|
||||
modules_toc.free()
|
||||
symbols_toc.free()
|
||||
return html_content.replace('{{ title }}', dcs.head.name).replace('{{ head_name }}',
|
||||
header_name).replace('{{ version }}', version).replace('{{ light_icon }}', cfg.assets['light_icon']).replace('{{ dark_icon }}',
|
||||
cfg.assets['dark_icon']).replace('{{ menu_icon }}', cfg.assets['menu_icon']).replace('{{ head_assets }}',
|
||||
|
|
@ -524,12 +502,12 @@ fn (cfg DocConfig) gen_html(idx int) string {
|
|||
'\n <link rel="stylesheet" href="' + cfg.assets['doc_css'] + '" />\n <link rel="stylesheet" href="' +
|
||||
cfg.assets['normalize_css'] + '" />'
|
||||
}).replace('{{ toc_links }}', if cfg.is_multi || cfg.docs.len > 1 {
|
||||
toc2.str()
|
||||
modules_toc_str
|
||||
} else {
|
||||
toc.str()
|
||||
symbols_toc_str
|
||||
}).replace('{{ contents }}', contents.str()).replace('{{ right_content }}', if cfg.is_multi &&
|
||||
cfg.docs.len > 1 && dcs.head.name != 'README' {
|
||||
'<div class="doc-toc"><ul>' + toc.str() + '</ul></div>'
|
||||
'<div class="doc-toc"><ul>' + symbols_toc_str + '</ul></div>'
|
||||
} else {
|
||||
''
|
||||
}).replace('{{ footer_content }}', cfg.gen_footer_text(idx)).replace('{{ footer_assets }}',
|
||||
|
|
@ -547,14 +525,13 @@ fn (cfg DocConfig) gen_plaintext(idx int) string {
|
|||
if dcs.head.comment.trim_space().len > 0 && !cfg.pub_only {
|
||||
pw.writeln(dcs.head.comment.split_into_lines().map(' ' + it).join('\n'))
|
||||
}
|
||||
for cn in dcs.contents {
|
||||
for _, cn in dcs.contents {
|
||||
pw.writeln(cn.content)
|
||||
if cn.comment.len > 0 && !cfg.pub_only {
|
||||
pw.writeln(cn.comment.trim_space().split_into_lines().map(' ' + it).join('\n'))
|
||||
}
|
||||
if cfg.show_loc {
|
||||
pw.writeln('Location: $cn.file_path:$cn.pos.line')
|
||||
pw.write('\n')
|
||||
pw.writeln('Location: $cn.file_path:$cn.pos.line\n')
|
||||
}
|
||||
}
|
||||
return pw.str()
|
||||
|
|
@ -568,7 +545,7 @@ fn (cfg DocConfig) gen_markdown(idx int, with_toc bool) string {
|
|||
if with_toc {
|
||||
hw.writeln('## Contents')
|
||||
}
|
||||
for cn in dcs.contents {
|
||||
for _, cn in dcs.contents {
|
||||
name := cn.name.all_after(dcs.head.name + '.')
|
||||
if with_toc {
|
||||
hw.writeln('- [#$name](${slug(name)})')
|
||||
|
|
@ -595,7 +572,7 @@ fn (cfg DocConfig) gen_footer_text(idx int) string {
|
|||
|
||||
fn (cfg DocConfig) render_doc(doc doc.Doc, i int) (string, string) {
|
||||
// since builtin is generated first, ignore it
|
||||
mut name := if ('vlib' in cfg.input_path &&
|
||||
mut name := if (doc.is_vlib &&
|
||||
doc.head.name == 'builtin' && !cfg.include_readme) ||
|
||||
doc.head.name == 'README' {
|
||||
'index'
|
||||
|
|
@ -627,7 +604,7 @@ fn (cfg DocConfig) work_processor(mut work sync.Channel, mut wg sync.WaitGroup)
|
|||
}
|
||||
file_name, content := cfg.render_doc(pdoc.d, pdoc.i)
|
||||
output_path := os.join_path(cfg.output_path, file_name)
|
||||
println('Generating ${output_path}...')
|
||||
println('Generating ${output_path}')
|
||||
os.write_file(output_path, content)
|
||||
}
|
||||
wg.done()
|
||||
|
|
@ -660,17 +637,16 @@ fn (cfg DocConfig) render() map[string]string {
|
|||
}
|
||||
|
||||
fn (mut cfg DocConfig) render_static() {
|
||||
if cfg.output_type == .html {
|
||||
if cfg.output_type != .html { return }
|
||||
cfg.assets = {
|
||||
'doc_css': cfg.get_resource(css_js_assets[0], true)
|
||||
'normalize_css': cfg.get_resource(css_js_assets[1], true)
|
||||
'doc_js': cfg.get_resource(css_js_assets[2], !cfg.serve_http)
|
||||
'light_icon': cfg.get_resource('light.svg', true)
|
||||
'dark_icon': cfg.get_resource('dark.svg', true)
|
||||
'menu_icon': cfg.get_resource('menu.svg', true)
|
||||
'doc_css': cfg.get_resource(css_js_assets[0], true),
|
||||
'normalize_css': cfg.get_resource(css_js_assets[1], true),
|
||||
'doc_js': cfg.get_resource(css_js_assets[2], !cfg.serve_http),
|
||||
'light_icon': cfg.get_resource('light.svg', true),
|
||||
'dark_icon': cfg.get_resource('dark.svg', true),
|
||||
'menu_icon': cfg.get_resource('menu.svg', true),
|
||||
'arrow_icon': cfg.get_resource('arrow.svg', true)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
fn (cfg DocConfig) get_readme(path string) string {
|
||||
|
|
@ -692,6 +668,20 @@ fn (cfg DocConfig) get_readme(path string) string {
|
|||
return readme_contents
|
||||
}
|
||||
|
||||
fn (cfg DocConfig) emit_generate_err(err string, errcode int) {
|
||||
mut err_msg := err
|
||||
if errcode == 1 {
|
||||
mod_list := get_modules_list(cfg.input_path, []string{})
|
||||
println('Available modules:\n==================')
|
||||
for mod in mod_list {
|
||||
println(mod.all_after('vlib/').all_after('modules/').replace('/',
|
||||
'.'))
|
||||
}
|
||||
err_msg += ' Use the `-m` flag when generating docs from a directory that has multiple modules.'
|
||||
}
|
||||
eprintln(err_msg)
|
||||
}
|
||||
|
||||
fn (mut cfg DocConfig) generate_docs_from_file() {
|
||||
if cfg.output_path.len == 0 {
|
||||
if cfg.output_type == .unset {
|
||||
|
|
@ -739,69 +729,53 @@ fn (mut cfg DocConfig) generate_docs_from_file() {
|
|||
}
|
||||
}
|
||||
dirs := if cfg.is_multi { get_modules_list(cfg.input_path, []string{}) } else { [cfg.input_path] }
|
||||
is_local_and_single := cfg.is_local && !cfg.is_multi
|
||||
for dirpath in dirs {
|
||||
cfg.vprintln('Generating docs for ${dirpath}...')
|
||||
if cfg.is_local && !cfg.is_multi {
|
||||
dcs := doc.generate_from_pos(dirpath, cfg.local_filename, cfg.local_pos) or {
|
||||
mut err_msg := err
|
||||
if errcode == 1 {
|
||||
mod_list := get_modules_list(cfg.input_path, []string{})
|
||||
println('Available modules:\n==================')
|
||||
for mod in mod_list {
|
||||
println(mod.all_after('vlib/').all_after('modules/').replace('/',
|
||||
'.'))
|
||||
}
|
||||
err_msg += ' Use the `-m` flag when generating docs from a directory that has multiple modules.'
|
||||
}
|
||||
eprintln(err_msg)
|
||||
mut dcs := doc.Doc{}
|
||||
cfg.vprintln('Generating docs for ${dirpath}')
|
||||
if is_local_and_single {
|
||||
dcs = doc.generate_from_pos(dirpath, cfg.local_filename, cfg.local_pos) or {
|
||||
cfg.emit_generate_err(err, errcode)
|
||||
exit(1)
|
||||
}
|
||||
if dcs.contents.len == 0 {
|
||||
continue
|
||||
}
|
||||
cfg.docs << dcs
|
||||
} else {
|
||||
mut dcs := doc.generate(dirpath, cfg.pub_only, true) or {
|
||||
mut err_msg := err
|
||||
if errcode == 1 {
|
||||
mod_list := get_modules_list(cfg.input_path, []string{})
|
||||
println('Available modules:\n==================')
|
||||
for mod in mod_list {
|
||||
println(mod.all_after('vlib/').all_after('modules/').replace('/',
|
||||
'.'))
|
||||
}
|
||||
err_msg += ' Use the `-m` flag when generating docs from a directory that has multiple modules.'
|
||||
}
|
||||
eprintln(err_msg)
|
||||
dcs = doc.generate(dirpath, cfg.pub_only, true) or {
|
||||
cfg.emit_generate_err(err, errcode)
|
||||
exit(1)
|
||||
}
|
||||
}
|
||||
if dcs.contents.len == 0 {
|
||||
continue
|
||||
}
|
||||
if !is_local_and_single {
|
||||
if cfg.is_multi || (!cfg.is_multi && cfg.include_readme) {
|
||||
readme_contents := cfg.get_readme(dirpath)
|
||||
dcs.head.comment = readme_contents
|
||||
}
|
||||
mut new_contents := map[string]doc.DocNode
|
||||
if cfg.pub_only {
|
||||
for i, c in dcs.contents {
|
||||
dcs.contents[i].content = c.content.all_after('pub ')
|
||||
for name, oc in dcs.contents {
|
||||
mut c := oc
|
||||
c.content = c.content.all_after('pub ')
|
||||
for i, cc in c.children {
|
||||
c.children[i].content = cc.content.all_after('pub ')
|
||||
}
|
||||
new_contents[name] = c
|
||||
}
|
||||
}
|
||||
if !cfg.is_multi && cfg.symbol_name.len > 0 {
|
||||
mut new_contents := []doc.DocNode{}
|
||||
for cn in dcs.contents {
|
||||
if cn.name != cfg.symbol_name {
|
||||
continue
|
||||
if cfg.symbol_name in dcs.contents {
|
||||
new_contents[cfg.symbol_name] = dcs.contents[cfg.symbol_name]
|
||||
children := dcs.contents[cfg.symbol_name].children
|
||||
for _, c in children {
|
||||
new_contents[c.name] = c
|
||||
}
|
||||
}
|
||||
new_contents << cn
|
||||
break
|
||||
}
|
||||
new_contents << dcs.contents.find_children_of(cfg.symbol_name)
|
||||
dcs.contents = new_contents
|
||||
}
|
||||
cfg.docs << dcs
|
||||
}
|
||||
}
|
||||
if 'vlib' in cfg.input_path {
|
||||
mut docs := cfg.docs.filter(it.head.name == 'builtin')
|
||||
docs << cfg.docs.filter(it.head.name != 'builtin')
|
||||
|
|
@ -890,22 +864,6 @@ fn get_ignore_paths(path string) ?[]string {
|
|||
return res.map(it.replace('/', os.path_separator))
|
||||
}
|
||||
|
||||
fn lookup_module(mod string) ?string {
|
||||
mod_path := mod.replace('.', os.path_separator)
|
||||
compile_dir := os.real_path(os.dir('.'))
|
||||
modules_dir := os.join_path(compile_dir, 'modules', mod_path)
|
||||
vlib_path := os.join_path(vexe_path, 'vlib', mod_path)
|
||||
vmodules_path := os.join_path(os.home_dir(), '.vmodules', mod_path)
|
||||
paths := [modules_dir, vlib_path, vmodules_path]
|
||||
for path in paths {
|
||||
if os.is_dir_empty(path) {
|
||||
continue
|
||||
}
|
||||
return path
|
||||
}
|
||||
return error('vdoc: Module "$mod" not found.')
|
||||
}
|
||||
|
||||
fn is_included(path string, ignore_paths []string) bool {
|
||||
if path.len == 0 {
|
||||
return true
|
||||
|
|
@ -946,7 +904,7 @@ fn get_modules_list(path string, ignore_paths2 []string) []string {
|
|||
fn (cfg DocConfig) get_resource(name string, minify bool) string {
|
||||
path := os.join_path(res_path, name)
|
||||
mut res := os.read_file(path) or {
|
||||
panic('could not read $path')
|
||||
panic('vdoc: could not read $path')
|
||||
}
|
||||
if minify {
|
||||
if name.ends_with('.js') {
|
||||
|
|
@ -961,7 +919,7 @@ fn (cfg DocConfig) get_resource(name string, minify bool) string {
|
|||
} else {
|
||||
output_path := os.join_path(cfg.output_path, name)
|
||||
if !os.exists(output_path) {
|
||||
println('Generating ${output_path}...')
|
||||
println('Generating ${output_path}')
|
||||
os.write_file(output_path, res)
|
||||
}
|
||||
return name
|
||||
|
|
@ -1071,6 +1029,9 @@ fn main() {
|
|||
eprintln('vdoc: No input path found.')
|
||||
exit(1)
|
||||
}
|
||||
if cfg.output_path == 'stdout' && cfg.output_type == .html {
|
||||
cfg.inline_assets = true
|
||||
}
|
||||
$if windows {
|
||||
cfg.input_path = cfg.input_path.replace('/', os.path_separator)
|
||||
} $else {
|
||||
|
|
@ -1083,8 +1044,8 @@ fn main() {
|
|||
cfg.input_path = os.join_path(vexe_path, 'vlib')
|
||||
} else if !is_path {
|
||||
cfg.vprintln('Input "$cfg.input_path" is not a valid path. Looking for modules named "$cfg.input_path"...')
|
||||
mod_path := lookup_module(cfg.input_path) or {
|
||||
eprintln(err)
|
||||
mod_path := doc.lookup_module(cfg.input_path) or {
|
||||
eprintln('vdoc: $err')
|
||||
exit(1)
|
||||
}
|
||||
cfg.input_path = mod_path
|
||||
|
|
|
|||
269
vlib/v/doc/doc.v
269
vlib/v/doc/doc.v
|
|
@ -13,8 +13,22 @@ import v.table
|
|||
import v.token
|
||||
import v.util
|
||||
|
||||
// intentionally in order as a guide when arranging the docnodes
|
||||
pub enum SymbolKind {
|
||||
none_
|
||||
typedef
|
||||
interface_
|
||||
const_group
|
||||
const_field
|
||||
enum_
|
||||
variable
|
||||
function
|
||||
method
|
||||
struct_
|
||||
}
|
||||
|
||||
pub struct Doc {
|
||||
prefs &pref.Preferences
|
||||
prefs &pref.Preferences = new_vdoc_preferences()
|
||||
pub mut:
|
||||
input_path string
|
||||
table &table.Table = &table.Table{}
|
||||
|
|
@ -23,17 +37,18 @@ pub mut:
|
|||
cur_fn: 0
|
||||
pref: 0
|
||||
}
|
||||
pub_only bool = true
|
||||
head DocNode
|
||||
with_comments bool = true
|
||||
contents []DocNode
|
||||
fmt fmt.Fmt
|
||||
time_generated time.Time
|
||||
with_pos bool
|
||||
with_head bool = true
|
||||
filename string
|
||||
pos int
|
||||
pub_only bool = true
|
||||
with_comments bool = true
|
||||
with_pos bool
|
||||
with_head bool = true
|
||||
is_vlib bool
|
||||
time_generated time.Time
|
||||
head DocNode
|
||||
contents map[string]DocNode
|
||||
scoped_contents map[string]DocNode
|
||||
}
|
||||
|
||||
pub struct DocPos {
|
||||
|
|
@ -50,7 +65,12 @@ pub mut:
|
|||
comment string
|
||||
pos DocPos = DocPos{-1, -1, 0}
|
||||
file_path string
|
||||
kind SymbolKind
|
||||
deprecated bool
|
||||
parent_name string
|
||||
children []DocNode
|
||||
attrs map[string]string
|
||||
from_scope bool
|
||||
}
|
||||
|
||||
pub fn merge_comments(comments []ast.Comment) string {
|
||||
|
|
@ -136,13 +156,13 @@ pub fn (mut d Doc) get_signature(stmt ast.Stmt, file &ast.File) string {
|
|||
}
|
||||
|
||||
pub fn (d Doc) get_pos(stmt ast.Stmt) token.Position {
|
||||
match stmt {
|
||||
ast.FnDecl, ast.StructDecl, ast.EnumDecl, ast.InterfaceDecl, ast.ConstDecl { return stmt.pos }
|
||||
else { return token.Position{} }
|
||||
if stmt is ast.InterfaceDecl {
|
||||
return stmt.pos
|
||||
}
|
||||
return stmt.position()
|
||||
}
|
||||
|
||||
pub fn (d Doc) get_type_name(decl ast.TypeDecl) string {
|
||||
pub fn get_type_decl_name(decl ast.TypeDecl) string {
|
||||
match decl {
|
||||
ast.SumTypeDecl, ast.FnTypeDecl, ast.AliasTypeDecl { return decl.name }
|
||||
}
|
||||
|
|
@ -151,9 +171,9 @@ pub fn (d Doc) get_type_name(decl ast.TypeDecl) string {
|
|||
pub fn (d Doc) get_name(stmt ast.Stmt) string {
|
||||
match stmt {
|
||||
ast.FnDecl, ast.StructDecl, ast.EnumDecl, ast.InterfaceDecl { return stmt.name }
|
||||
ast.TypeDecl { return d.get_type_name(stmt) }
|
||||
ast.ConstDecl { return 'Constants' }
|
||||
else { return typeof(stmt) }
|
||||
ast.TypeDecl { return get_type_decl_name(stmt) }
|
||||
ast.ConstDecl { return '' } // leave it blank
|
||||
else { return '' }
|
||||
}
|
||||
}
|
||||
|
||||
|
|
@ -168,10 +188,9 @@ pub fn new_vdoc_preferences() &pref.Preferences {
|
|||
pub fn new(input_path string) Doc {
|
||||
mut d := Doc{
|
||||
input_path: os.real_path(input_path)
|
||||
prefs: new_vdoc_preferences()
|
||||
table: table.new_table()
|
||||
head: DocNode{}
|
||||
contents: []DocNode{}
|
||||
contents: map[string]DocNode{}
|
||||
time_generated: time.now()
|
||||
}
|
||||
d.fmt = fmt.Fmt{
|
||||
|
|
@ -187,8 +206,20 @@ pub fn (mut nodes []DocNode) sort_by_name() {
|
|||
nodes.sort_with_compare(compare_nodes_by_name)
|
||||
}
|
||||
|
||||
pub fn (mut nodes []DocNode) sort_by_category() {
|
||||
nodes.sort_with_compare(compare_nodes_by_category)
|
||||
pub fn (mut nodes []DocNode) sort_by_kind() {
|
||||
nodes.sort_with_compare(compare_nodes_by_kind)
|
||||
}
|
||||
|
||||
fn compare_nodes_by_kind(a &DocNode, b &DocNode) int {
|
||||
ak := int((*a).kind)
|
||||
bk := int((*b).kind)
|
||||
if ak < bk {
|
||||
return -1
|
||||
}
|
||||
if ak > bk {
|
||||
return 1
|
||||
}
|
||||
return 0
|
||||
}
|
||||
|
||||
fn compare_nodes_by_name(a &DocNode, b &DocNode) int {
|
||||
|
|
@ -197,39 +228,11 @@ fn compare_nodes_by_name(a &DocNode, b &DocNode) int {
|
|||
return compare_strings(al, bl)
|
||||
}
|
||||
|
||||
fn compare_nodes_by_category(a &DocNode, b &DocNode) int {
|
||||
al := a.attrs['category']
|
||||
bl := b.attrs['category']
|
||||
return compare_strings(al, bl)
|
||||
}
|
||||
|
||||
pub fn (nodes []DocNode) index_by_name(node_name string) int {
|
||||
for i, node in nodes {
|
||||
if node.name != node_name {
|
||||
continue
|
||||
}
|
||||
return i
|
||||
}
|
||||
return -1
|
||||
}
|
||||
|
||||
pub fn (nodes []DocNode) find_children_of(parent string) []DocNode {
|
||||
return nodes.find_nodes_with_attr('parent', parent)
|
||||
}
|
||||
|
||||
pub fn (nodes []DocNode) find_nodes_with_attr(attr_name string, value string) []DocNode {
|
||||
mut subgroup := []DocNode{}
|
||||
if attr_name.len == 0 {
|
||||
return subgroup
|
||||
}
|
||||
for node in nodes {
|
||||
if !node.attrs.exists(attr_name) || node.attrs[attr_name] != value {
|
||||
continue
|
||||
}
|
||||
subgroup << node
|
||||
}
|
||||
subgroup.sort_by_name()
|
||||
return subgroup
|
||||
pub fn (cnts map[string]DocNode) arr() []DocNode {
|
||||
mut contents := cnts.keys().map(cnts[it])
|
||||
contents.sort_by_name()
|
||||
contents.sort_by_kind()
|
||||
return contents
|
||||
}
|
||||
|
||||
// get_parent_mod - return the parent mod name, in dot format.
|
||||
|
|
@ -250,9 +253,9 @@ fn get_parent_mod(input_dir string) ?string {
|
|||
}
|
||||
}
|
||||
base_dir := os.dir(input_dir)
|
||||
input_dir_name := os.file_name(input_dir)
|
||||
input_dir_name := os.file_name(base_dir)
|
||||
prefs := new_vdoc_preferences()
|
||||
fentries := os.ls(input_dir) or {
|
||||
fentries := os.ls(base_dir) or {
|
||||
[]string{}
|
||||
}
|
||||
files := fentries.filter(!os.is_dir(it))
|
||||
|
|
@ -260,7 +263,7 @@ fn get_parent_mod(input_dir string) ?string {
|
|||
// the top level is reached, no point in climbing up further
|
||||
return ''
|
||||
}
|
||||
v_files := prefs.should_compile_filtered_files(input_dir, files)
|
||||
v_files := prefs.should_compile_filtered_files(base_dir, files)
|
||||
if v_files.len == 0 {
|
||||
parent_mod := get_parent_mod(base_dir) or {
|
||||
return input_dir_name
|
||||
|
|
@ -279,17 +282,17 @@ fn get_parent_mod(input_dir string) ?string {
|
|||
return ''
|
||||
}
|
||||
parent_mod := get_parent_mod(base_dir) or {
|
||||
return error(err)
|
||||
return input_dir_name
|
||||
}
|
||||
if parent_mod.len > 0 {
|
||||
return parent_mod
|
||||
return '${parent_mod}.$file_ast.mod.name'
|
||||
}
|
||||
return file_ast.mod.name
|
||||
}
|
||||
|
||||
pub fn (mut d Doc) generate_from_ast(file_ast ast.File, orig_mod_name string) []DocNode {
|
||||
mut const_idx := -1
|
||||
mut contents := []DocNode{}
|
||||
pub fn (mut d Doc) generate_from_ast(file_ast ast.File) map[string]DocNode {
|
||||
mut contents := map[string]DocNode{}
|
||||
orig_mod_name := file_ast.mod.name
|
||||
stmts := file_ast.stmts
|
||||
d.fmt.file = file_ast
|
||||
d.fmt.set_current_module_name(orig_mod_name)
|
||||
|
|
@ -364,80 +367,82 @@ pub fn (mut d Doc) generate_from_ast(file_ast ast.File, orig_mod_name string) []
|
|||
}
|
||||
match stmt {
|
||||
ast.ConstDecl {
|
||||
if const_idx == -1 {
|
||||
const_idx = sidx
|
||||
} else {
|
||||
node.attrs['parent'] = 'Constants'
|
||||
node.kind = .const_group
|
||||
node.parent_name = 'Constants'
|
||||
if node.parent_name !in contents {
|
||||
contents[node.parent_name] = DocNode{
|
||||
name: 'Constants'
|
||||
kind: .const_group
|
||||
}
|
||||
}
|
||||
node.attrs['category'] = 'Constants'
|
||||
}
|
||||
ast.EnumDecl {
|
||||
node.attrs['category'] = 'Enums'
|
||||
node.kind = .enum_
|
||||
}
|
||||
ast.InterfaceDecl {
|
||||
node.attrs['category'] = 'Interfaces'
|
||||
node.kind = .interface_
|
||||
}
|
||||
ast.StructDecl {
|
||||
node.attrs['category'] = 'Structs'
|
||||
node.kind = .struct_
|
||||
}
|
||||
ast.TypeDecl {
|
||||
node.attrs['category'] = 'Typedefs'
|
||||
node.kind = .typedef
|
||||
}
|
||||
ast.FnDecl {
|
||||
if stmt.is_deprecated {
|
||||
continue
|
||||
}
|
||||
if stmt.receiver.typ != 0 {
|
||||
node.attrs['parent'] = d.fmt.table.type_to_str(stmt.receiver.typ).trim_left('&')
|
||||
p_idx := contents.index_by_name(node.attrs['parent'])
|
||||
if p_idx == -1 && node.attrs['parent'] != 'void' {
|
||||
contents << DocNode{
|
||||
name: node.attrs['parent']
|
||||
content: ''
|
||||
comment: ''
|
||||
attrs: {
|
||||
'category': 'Structs'
|
||||
node.deprecated = stmt.is_deprecated
|
||||
node.kind = .function
|
||||
if stmt.receiver.typ !in [0, 1] {
|
||||
method_parent := d.fmt.table.type_to_str(stmt.receiver.typ).trim_left('&')
|
||||
if method_parent != 'void' && method_parent !in contents {
|
||||
contents[method_parent] = DocNode{
|
||||
name: method_parent
|
||||
kind: .none_
|
||||
}
|
||||
}
|
||||
node.kind = .method
|
||||
node.parent_name = method_parent
|
||||
}
|
||||
}
|
||||
node.attrs['category'] = if node.attrs['parent'] in ['void', ''] || !node.attrs.exists('parent') { 'Functions' } else { 'Methods' }
|
||||
}
|
||||
else {}
|
||||
}
|
||||
contents << node
|
||||
if d.with_comments && (prev_comments.len > 0) {
|
||||
last_comment := contents[contents.len - 1].comment
|
||||
cmt := last_comment + '\n' + get_comment_block_right_before(prev_comments)
|
||||
contents[contents.len - 1].comment = cmt
|
||||
// last_comment := contents[contents.len - 1].comment
|
||||
// cmt := last_comment + '\n' + get_comment_block_right_before(prev_comments)
|
||||
cmt := get_comment_block_right_before(prev_comments)
|
||||
node.comment = cmt
|
||||
}
|
||||
prev_comments = []
|
||||
if node.parent_name.len > 0 {
|
||||
parent_name := node.parent_name
|
||||
if node.parent_name == 'Constants' {
|
||||
node.parent_name = ''
|
||||
}
|
||||
contents[parent_name].children << node
|
||||
} else {
|
||||
contents[node.name] = node
|
||||
}
|
||||
}
|
||||
d.fmt.mod2alias = map[string]string{}
|
||||
return contents
|
||||
}
|
||||
|
||||
pub fn (mut d Doc) generate_from_ast_with_pos(file_ast ast.File, pos int) []DocNode {
|
||||
pub fn (mut d Doc) generate_from_ast_with_pos(file_ast ast.File, pos int) map[string]DocNode {
|
||||
lscope := file_ast.scope.innermost(pos)
|
||||
mut contents := []DocNode{}
|
||||
mut contents := map[string]DocNode{}
|
||||
for name, val in lscope.objects {
|
||||
if val !is ast.Var {
|
||||
continue
|
||||
}
|
||||
vr_data := val as ast.Var
|
||||
vr_expr := vr_data.expr
|
||||
l_node := DocNode{
|
||||
name: name
|
||||
content: ''
|
||||
comment: ''
|
||||
pos: convert_pos(file_ast.path, vr_data.pos)
|
||||
file_path: file_ast.path
|
||||
attrs: {
|
||||
'category': 'Variable'
|
||||
'return_type': d.expr_typ_to_string(vr_expr)
|
||||
'local': 'true'
|
||||
from_scope: true
|
||||
kind: .variable
|
||||
parent_name: d.expr_typ_to_string(vr_data.expr)
|
||||
}
|
||||
}
|
||||
contents << l_node
|
||||
contents[l_node.name] = l_node
|
||||
}
|
||||
return contents
|
||||
}
|
||||
|
|
@ -459,30 +464,27 @@ fn (mut d Doc) generate() ?Doc {
|
|||
return error_with_code('vdoc: No valid V files were found.', 1)
|
||||
}
|
||||
// parse files
|
||||
mut file_asts := []ast.File{}
|
||||
// TODO: remove later for vlib
|
||||
comments_mode := if d.with_comments { scanner.CommentsMode.toplevel_comments } else { scanner.CommentsMode.skip_comments }
|
||||
mut fname_has_set := false
|
||||
for file in v_files {
|
||||
file_ast := parser.parse_file(file, d.table, comments_mode, d.prefs, &ast.Scope{
|
||||
mut comments_mode := scanner.CommentsMode.skip_comments
|
||||
if d.with_comments {
|
||||
comments_mode = .toplevel_comments
|
||||
}
|
||||
global_scope := &ast.Scope{
|
||||
parent: 0
|
||||
})
|
||||
}
|
||||
mut parent_mod_name := ''
|
||||
mut fname_has_set := false
|
||||
mut orig_mod_name := ''
|
||||
for i, file in v_files {
|
||||
file_ast := parser.parse_file(file, d.table, comments_mode, d.prefs, global_scope)
|
||||
if d.filename.len > 0 && d.filename in file && !fname_has_set {
|
||||
d.filename = file
|
||||
fname_has_set = true
|
||||
}
|
||||
file_asts << file_ast
|
||||
}
|
||||
mut module_name := ''
|
||||
mut parent_mod_name := ''
|
||||
mut orig_mod_name := ''
|
||||
for i, file_ast in file_asts {
|
||||
d.checker.check(file_ast)
|
||||
if i == 0 {
|
||||
parent_mod_name = get_parent_mod(base_path) or {
|
||||
''
|
||||
}
|
||||
module_name = file_ast.mod.name
|
||||
mut module_name := file_ast.mod.name
|
||||
orig_mod_name = module_name
|
||||
if module_name != 'main' && parent_mod_name.len > 0 {
|
||||
module_name = parent_mod_name + '.' + module_name
|
||||
|
|
@ -491,21 +493,27 @@ fn (mut d Doc) generate() ?Doc {
|
|||
d.head = DocNode{
|
||||
name: module_name
|
||||
content: 'module $module_name'
|
||||
comment: ''
|
||||
kind: .none_
|
||||
}
|
||||
}
|
||||
} else if file_ast.mod.name != orig_mod_name {
|
||||
continue
|
||||
}
|
||||
d.contents << d.generate_from_ast(file_ast, orig_mod_name)
|
||||
if file_ast.path == d.filename {
|
||||
d.contents << d.generate_from_ast_with_pos(file_ast, d.pos)
|
||||
d.checker.check(file_ast)
|
||||
d.scoped_contents = d.generate_from_ast_with_pos(file_ast, d.pos)
|
||||
}
|
||||
contents := d.generate_from_ast(file_ast)
|
||||
for name, node in contents {
|
||||
if name in d.contents && (d.contents[name].kind != .none_ || node.kind == .none_) {
|
||||
d.contents[name].children << node.children
|
||||
d.contents[name].children.sort_by_name()
|
||||
continue
|
||||
}
|
||||
d.contents[name] = node
|
||||
}
|
||||
d.fmt.mod2alias = map[string]string{}
|
||||
}
|
||||
d.time_generated = time.now()
|
||||
d.contents.sort_by_name()
|
||||
d.contents.sort_by_category()
|
||||
return *d
|
||||
}
|
||||
|
||||
|
|
@ -525,3 +533,24 @@ pub fn generate(input_path string, pub_only bool, with_comments bool) ?Doc {
|
|||
doc.with_comments = with_comments
|
||||
return doc.generate()
|
||||
}
|
||||
|
||||
pub fn lookup_module(mod string) ?string {
|
||||
mod_path := mod.replace('.', os.path_separator)
|
||||
compile_dir := os.real_path(os.dir('.'))
|
||||
modules_dir := os.join_path(compile_dir, 'modules', mod_path)
|
||||
vlib_path := os.join_path(os.dir(@VEXE), 'vlib', mod_path)
|
||||
vmodules_path := os.join_path(os.home_dir(), '.vmodules', mod_path)
|
||||
paths := [modules_dir, vlib_path, vmodules_path]
|
||||
for path in paths {
|
||||
if !os.exists(path) || os.is_dir_empty(path) {
|
||||
continue
|
||||
}
|
||||
return path
|
||||
}
|
||||
return error('module "$mod" not found.')
|
||||
}
|
||||
|
||||
pub fn generate_from_mod(module_name string, pub_only bool, with_comments bool) ?Doc {
|
||||
mod_path := lookup_module(module_name) ?
|
||||
return generate(mod_path, pub_only, with_comments)
|
||||
}
|
||||
|
|
|
|||
|
|
@ -1,9 +1,19 @@
|
|||
// import v.table
|
||||
// import v.doc
|
||||
// import v.pref
|
||||
// fn test_vdoc() {
|
||||
// mut prefs := &pref.Preferences{}
|
||||
// prefs.fill_with_defaults()
|
||||
// table := table.new_table()
|
||||
// println(doc.doc('net', table, prefs))
|
||||
// }
|
||||
import v.doc
|
||||
import v.parser
|
||||
|
||||
// fn test_generate_with_pos() {}
|
||||
// fn test_generate() {}
|
||||
// fn test_generate_from_ast() {}
|
||||
fn test_generate_from_mod() {
|
||||
nested_mod_name := 'net.http.chunked'
|
||||
nested_mod_doc := doc.generate_from_mod(nested_mod_name, false, true) or {
|
||||
eprintln(err)
|
||||
assert false
|
||||
doc.Doc{}
|
||||
}
|
||||
assert nested_mod_doc.head.name == nested_mod_name
|
||||
assert nested_mod_doc.head.content == 'module $nested_mod_name'
|
||||
assert nested_mod_doc.contents.len == 3
|
||||
assert nested_mod_doc.contents['ChunkScanner'].children.len == 3
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in New Issue