vieter-v
/
v
2
0
Fork 0
Code Issues Pull Requests Releases Activity

vdoc: rewrite usage, add new options + streamline process

pull/5224/head
Ned Palacios 2020-06-05 15:59:26 +08:00 committed by GitHub
parent c9b395f9cf
commit 30e0bda434
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 226 additions and 129 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.gitignore vendored
View File

@ -67,3 +67,5 @@ cachegrind.out.*
._* ._*
thumbs.db thumbs.db
/.symlink/* /.symlink/*
_docs

323
cmd/tools/vdoc.v
View File

@ -7,16 +7,17 @@ import os
import os.cmdline import os.cmdline
import strings import strings
import v.doc import v.doc
import v.util
import v.vmod import v.vmod
const ( const (
allowed_formats = ['md', 'markdown', 'json', 'text', 'stdout', 'html', 'htm']
exe_path = os.executable() exe_path = os.executable()
exe_dir = os.dir(exe_path) exe_dir = os.dir(exe_path)
res_path = os.join_path(exe_dir, 'vdoc-resources') res_path = os.join_path(exe_dir, 'vdoc-resources')
) )
enum OutputType { enum OutputType {
unset
html html
markdown markdown
json json
@ -25,15 +26,18 @@ enum OutputType {
} }
struct DocConfig { struct DocConfig {
pub_only bool = true
show_loc bool = false // for plaintext
serve_http bool = false // for html
is_multi bool = false
include_readme bool = false
mut: mut:
opath string pub_only bool = true
src_path string show_loc bool = false // for plaintext
docs []doc.Doc serve_http bool = false // for html
is_multi bool = false
is_verbose bool = false
include_readme bool = false
inline_assets bool = false
output_path string
input_path string
output_type OutputType = .unset
docs []doc.Doc
manifest vmod.Manifest manifest vmod.Manifest
} }
@ -54,7 +58,7 @@ fn open_url(url string) {
} }
fn (mut cfg DocConfig) serve_html() { fn (mut cfg DocConfig) serve_html() {
docs := cfg.multi_render(.html) docs := cfg.render()
def_name := docs.keys()[0] def_name := docs.keys()[0]
server := net.listen(8046) or { server := net.listen(8046) or {
panic(err) panic(err)
@ -113,7 +117,7 @@ fn (cfg DocConfig) gen_json(idx int) string {
mut jw := strings.new_builder(200) mut jw := strings.new_builder(200)
jw.writeln('{\n\t"module_name": "$dcs.head.name",\n\t"description": "${escape(dcs.head.comment)}",\n\t"contents": [') jw.writeln('{\n\t"module_name": "$dcs.head.name",\n\t"description": "${escape(dcs.head.comment)}",\n\t"contents": [')
for i, cn in dcs.contents { for i, cn in dcs.contents {
name := cn.name[dcs.head.name.len+1..] name := cn.name.all_after(dcs.head.name)
jw.writeln('\t\t{') jw.writeln('\t\t{')
jw.writeln('\t\t\t"name": "$name",') jw.writeln('\t\t\t"name": "$name",')
jw.writeln('\t\t\t"signature": "${escape(cn.content)}",') jw.writeln('\t\t\t"signature": "${escape(cn.content)}",')
@ -174,20 +178,25 @@ fn (cfg DocConfig) gen_html(idx int) string {
<meta http-equiv="x-ua-compatible" content="IE=edge" /> <meta http-equiv="x-ua-compatible" content="IE=edge" />
<meta name="viewport" content="width=device-width, initial-scale=1.0"> <meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>${dcs.head.name} | vdoc</title> <title>${dcs.head.name} | vdoc</title>
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600&family=Source+Code+Pro:wght@500&display=swap" rel="stylesheet"> <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600&family=Source+Code+Pro:wght@500&display=swap" rel="stylesheet" />
<link rel="stylesheet" href="https://necolas.github.io/normalize.css/8.0.1/normalize.css">') <link rel="stylesheet" href="https://necolas.github.io/normalize.css/8.0.1/normalize.css" />')
// get resources // get resources
doc_css_min := get_resource('doc.css', true) doc_css_min := cfg.get_resource('doc.css', true)
light_icon := get_resource('light.svg', true) light_icon := cfg.get_resource('light.svg', true)
dark_icon := get_resource('dark.svg', true) dark_icon := cfg.get_resource('dark.svg', true)
menu_icon := get_resource('menu.svg', true) menu_icon := cfg.get_resource('menu.svg', true)
arrow_icon := get_resource('arrow.svg', true) arrow_icon := cfg.get_resource('arrow.svg', true)
// write css // write css
hw.write('<style>$doc_css_min</style>') if cfg.inline_assets {
hw.write('<style>$doc_css_min</style>')
} else {
hw.write('\n <link rel="stylesheet" href="$doc_css_min" />')
}
version := if cfg.manifest.version.len != 0 { cfg.manifest.version } else { '' } version := if cfg.manifest.version.len != 0 { cfg.manifest.version } else { '' }
header_name := if cfg.is_multi && cfg.docs.len > 1 { os.file_name(os.real_path(cfg.src_path)) } else { dcs.head.name } header_name := if cfg.is_multi && cfg.docs.len > 1 { os.file_name(os.real_path(cfg.input_path)) } else { dcs.head.name }
// write nav1 // write nav1
hw.write(' hw.write('
<body> <body>
@ -253,7 +262,7 @@ fn (cfg DocConfig) gen_html(idx int) string {
hw.write(doc_node_html(dcs.head, '', true)) hw.write(doc_node_html(dcs.head, '', true))
for cn in dcs.contents { for cn in dcs.contents {
if cn.parent_type !in ['void', ''] { continue } if cn.parent_type !in ['void', ''] { continue }
base_dir := os.base_dir(os.real_path(cfg.src_path)) base_dir := os.base_dir(os.real_path(cfg.input_path))
file_path_name := cn.file_path.replace('$base_dir/', '') file_path_name := cn.file_path.replace('$base_dir/', '')
hw.write(doc_node_html(cn, get_src_link(cfg.manifest.repo_url, file_path_name, cn.pos.line), false)) hw.write(doc_node_html(cn, get_src_link(cfg.manifest.repo_url, file_path_name, cn.pos.line), false))
@ -270,9 +279,14 @@ fn (cfg DocConfig) gen_html(idx int) string {
if cfg.is_multi && cfg.docs.len > 1 && dcs.head.name != 'README' { if cfg.is_multi && cfg.docs.len > 1 && dcs.head.name != 'README' {
hw.write('<div class="doc-toc">\n\n<ul>\n${toc.str()}</ul>\n</div>') hw.write('<div class="doc-toc">\n\n<ul>\n${toc.str()}</ul>\n</div>')
} }
doc_js_min := get_resource('doc.js', true) doc_js_min := cfg.get_resource('doc.js', false)
hw.write('</div></div><script>$doc_js_min</script> hw.write('</div></div>')
</body> if cfg.inline_assets {
hw.write('<script>$doc_js_min</script>')
} else {
hw.write('<script src="$doc_js_min"></script>')
}
hw.write('</body>
</html>') </html>')
return hw.str() return hw.str()
} }
@ -280,8 +294,7 @@ fn (cfg DocConfig) gen_html(idx int) string {
fn (cfg DocConfig) gen_plaintext(idx int) string { fn (cfg DocConfig) gen_plaintext(idx int) string {
dcs := cfg.docs[idx] dcs := cfg.docs[idx]
mut pw := strings.new_builder(200) mut pw := strings.new_builder(200)
head_lines := '='.repeat(dcs.head.content.len) pw.writeln('${dcs.head.content}\n')
pw.writeln('${dcs.head.content}\n$head_lines\n')
for cn in dcs.contents { for cn in dcs.contents {
pw.writeln(cn.content) pw.writeln(cn.content)
if cn.comment.len > 0 { if cn.comment.len > 0 {
@ -291,7 +304,6 @@ fn (cfg DocConfig) gen_plaintext(idx int) string {
pw.writeln('Location: ${cn.file_path}:${cn.pos.line}:${cn.pos.col}\n\n') pw.writeln('Location: ${cn.file_path}:${cn.pos.line}:${cn.pos.col}\n\n')
} }
} }
pw.writeln('Generated on $dcs.time_generated')
return pw.str() return pw.str()
} }
@ -317,82 +329,74 @@ fn (cfg DocConfig) gen_markdown(idx int, with_toc bool) string {
return hw.str() + '\n' + cw.str() return hw.str() + '\n' + cw.str()
} }
fn (cfg DocConfig) multi_render(output_type OutputType) map[string]string { fn (cfg DocConfig) render() map[string]string {
mut docs := map[string]string mut docs := map[string]string
for i, doc in cfg.docs { for i, doc in cfg.docs {
mut name := if doc.head.name == 'README' { mut name := if doc.head.name == 'README' {
'index' 'index'
} else if cfg.docs.len == 1 && !os.is_dir(cfg.opath) { } else if !cfg.is_multi && !os.is_dir(cfg.output_path) {
os.dir(os.file_name(cfg.opath)) os.file_name(cfg.output_path)
} else { } else {
doc.head.name doc.head.name
} }
name = name + match output_type { name = name + match cfg.output_type {
.html { '.html' } .html { '.html' }
.markdown { '.md' } .markdown { '.md' }
.json { '.json' } .json { '.json' }
else { '.txt' } else { '.txt' }
} }
docs[name] = match output_type { docs[name] = match cfg.output_type {
.html { cfg.gen_html(i) } .html { cfg.gen_html(i) }
.markdown { cfg.gen_markdown(i, true) } .markdown { cfg.gen_markdown(i, true) }
.json { cfg.gen_json(i) } .json { cfg.gen_json(i) }
else { cfg.gen_plaintext(i) } else { cfg.gen_plaintext(i) }
} }
} }
cfg.vprintln('Rendered: ' + docs.keys().str())
return docs return docs
} }
fn (mut config DocConfig) generate_docs_from_file() { fn (mut cfg DocConfig) generate_docs_from_file() {
if config.opath.len != 0 { if cfg.output_path.len == 0 {
config.opath = os.join_path(os.real_path(os.base_dir(config.opath)), os.file_name(config.opath)) if cfg.output_type == .unset {
} cfg.output_type = .stdout
println(config.opath)
mut output_type := OutputType.plaintext
// identify output type
if config.serve_http {
output_type = .html
} else if config.opath.len == 0 {
output_type = .stdout
} else {
ext := os.file_ext(config.opath)
if ext in ['.md', '.markdown'] || config.opath in [':md:', ':markdown:'] {
output_type = .markdown
} else if ext in ['.html', '.htm'] || config.opath == ':html:' {
output_type = .html
} else if ext == '.json' || config.opath == ':json:' {
output_type = .json
} else { } else {
output_type = .plaintext cfg.vprintln('No output path has detected. Using input path instead.')
cfg.output_path = cfg.input_path
} }
} else if cfg.output_type == .unset {
cfg.vprintln('Output path detected. Identifying output type..')
ext := os.file_ext(cfg.output_path)
cfg.set_output_type_from_str(ext.all_after('.'))
} }
if config.include_readme && output_type !in [.html, .stdout] { if cfg.include_readme && cfg.output_type !in [.html, .stdout] {
eprintln('vdoc: Including README.md for doc generation is supported on HTML output, or when running directly in the terminal.') eprintln('vdoc: Including README.md for doc generation is supported on HTML output, or when running directly in the terminal.')
exit(1) exit(1)
} }
mut manifest_path := os.join_path(if os.is_dir(config.src_path) { config.src_path } else { os.base_dir(config.src_path) }, 'v.mod') is_vlib := 'vlib' in cfg.input_path
if os.exists(manifest_path) && 'vlib' !in config.src_path { dir_path := if is_vlib {
os.base_dir(@VEXE)
} else if os.is_dir(cfg.input_path) {
cfg.input_path
} else {
os.base_dir(cfg.input_path)
}
manifest_path := os.join_path(dir_path, 'v.mod')
readme_path := os.join_path(dir_path, 'README.md')
if os.exists(manifest_path) {
cfg.vprintln('Reading v.mod info from $manifest_path')
if manifest := vmod.from_file(manifest_path) { if manifest := vmod.from_file(manifest_path) {
config.manifest = manifest cfg.manifest = manifest
} }
} }
if 'vlib' in config.src_path { if os.exists(readme_path) && cfg.include_readme {
config.manifest.version = util.v_version cfg.vprintln('Reading README file from $readme_path')
config.manifest.repo_url = 'https://github.com/vlang/v'
}
readme_path := if 'vlib' in config.src_path {
os.join_path(os.base_dir(@VEXE), 'README.md')
} else {
os.join_path(config.src_path, 'README.md')
}
// check README.md
if os.exists(readme_path) && config.include_readme {
readme_contents := os.read_file(readme_path) or { '' } readme_contents := os.read_file(readme_path) or { '' }
if output_type == .stdout { if cfg.output_type == .stdout {
println(readme_contents) println(markdown.to_plain(readme_contents))
} }
if output_type == .html { if cfg.output_type == .html {
config.docs << doc.Doc{ cfg.docs << doc.Doc{
head: doc.DocNode{ head: doc.DocNode{
name: 'README', name: 'README',
comment: readme_contents comment: readme_contents
@ -400,51 +404,77 @@ fn (mut config DocConfig) generate_docs_from_file() {
} }
} }
} }
if config.is_multi { dirs := if cfg.is_multi { get_modules_list(cfg.input_path) } else { [cfg.input_path] }
dirs := get_modules_list(config.src_path) for dirpath in dirs {
for dirpath in dirs { cfg.vprintln('Generating docs for ${dirpath}...')
dcs := doc.generate(dirpath, config.pub_only, 'vlib' !in config.src_path) or { dcs := doc.generate(dirpath, cfg.pub_only, !is_vlib) or {
panic(err)
}
if dcs.contents.len == 0 { continue }
config.docs << dcs
}
} else {
dcs := doc.generate(config.src_path, config.pub_only, 'vlib' !in config.src_path) or {
panic(err) panic(err)
} }
config.docs << dcs if dcs.contents.len == 0 { continue }
cfg.docs << dcs
} }
if config.serve_http { if cfg.serve_http {
config.serve_html() cfg.serve_html()
return return
} }
outputs := config.multi_render(output_type) cfg.vprintln('Rendering docs...')
if output_type == .stdout || (config.opath.starts_with(':') && config.opath.ends_with(':')) { if cfg.output_path.len == 0 {
outputs := cfg.render()
first := outputs.keys()[0] first := outputs.keys()[0]
println(outputs[first]) println(outputs[first])
} else { } else {
if !os.is_dir(config.opath) { if !os.is_dir(cfg.output_path) {
config.opath = os.base_dir(config.opath) cfg.output_path = os.real_path('.')
} }
if config.is_multi { if cfg.is_multi {
config.opath = os.join_path(config.opath, '_docs') cfg.output_path = os.join_path(cfg.output_path, '_docs')
if !os.exists(config.opath) { if !os.exists(cfg.output_path) {
os.mkdir(config.opath) or { os.mkdir(cfg.output_path) or {
panic(err) panic(err)
} }
} else {
os.rm(os.join_path(cfg.output_path, 'doc.css'))
os.rm(os.join_path(cfg.output_path, 'doc.js'))
} }
} }
outputs := cfg.render()
for file_name, content in outputs { for file_name, content in outputs {
opath := os.join_path(config.opath, file_name) output_path := os.join_path(cfg.output_path, file_name)
println('Generating ${opath}...') println('Generating ${output_path}...')
os.write_file(opath, content) os.write_file(output_path, content)
} }
} }
} }
fn (mut cfg DocConfig) set_output_type_from_str(format string) {
match format {
'htm', 'html' {
cfg.output_type = .html
}
'md', 'markdown' {
cfg.output_type = .markdown
}
'json' {
cfg.output_type = .json
}
'stdout' {
cfg.output_type = .stdout
}
else {
cfg.output_type = .plaintext
}
}
cfg.vprintln('Setting output type to "$cfg.output_type"')
}
fn (cfg DocConfig) vprintln(str string) {
if cfg.is_verbose {
println('vdoc: $str')
}
}
fn lookup_module(mod string) ?string { fn lookup_module(mod string) ?string {
mod_path := mod.replace('.', '/') mod_path := mod.replace('.', os.path_separator)
vexe_path := os.base_dir(@VEXE) vexe_path := os.base_dir(@VEXE)
compile_dir := os.real_path(os.base_dir('.')) compile_dir := os.real_path(os.base_dir('.'))
modules_dir := os.join_path(compile_dir, 'modules', mod_path) modules_dir := os.join_path(compile_dir, 'modules', mod_path)
@ -471,40 +501,97 @@ fn get_modules_list(path string) []string {
return dirs return dirs
} }
fn get_resource(name string, minify bool) string { fn (cfg DocConfig) get_resource(name string, minify bool) string {
path := os.join_path(res_path, name) path := os.join_path(res_path, name)
res := os.read_file(path) or { panic('could not read $path') } mut res := os.read_file(path) or { panic('could not read $path') }
if minify { if minify {
res.replace('\n', ' ') res = res.replace('\n', ' ')
}
// TODO: Make SVG inline for now
if cfg.inline_assets || path.ends_with('.svg') {
return res
} else {
output_path := os.join_path(cfg.output_path, name)
if !os.exists(output_path) {
println('Generating ${output_path}...')
os.write_file(output_path, res)
}
return name
} }
return res
} }
fn main() { fn main() {
args_after_doc := cmdline.options_after(os.args[1..], ['doc']) args := os.args[2..]
opts := cmdline.only_options(os.args[1..])
args := cmdline.only_non_options(args_after_doc)
if args.len == 0 || args[0] == 'help' { if args.len == 0 || args[0] == 'help' {
os.system('v help doc') os.system('v help doc')
exit(0) exit(0)
} }
mut config := DocConfig{ mut cfg := DocConfig{
src_path: args[0],
opath: if args.len >= 2 { args[1] } else { '' },
pub_only: '-all' !in opts,
show_loc: '-loc' in opts,
serve_http: '-s' in opts,
is_multi: '-m' in opts,
include_readme: '-r' in opts,
manifest: vmod.Manifest{ repo_url: '' } manifest: vmod.Manifest{ repo_url: '' }
} }
is_path := config.src_path.ends_with('.v') || config.src_path.split('/').len > 1 || config.src_path == '.' for i := 0; i < args.len; i++ {
if !is_path { arg := args[i]
mod_path := lookup_module(config.src_path) or { current_args := args[i..]
match arg {
'-all' {
cfg.pub_only = false
}
'-f' {
format := cmdline.option(current_args, '-f', '')
allowed_str := allowed_formats.join(', ')
if format !in allowed_formats {
eprintln('vdoc: "$format" is not a valid format. Only $allowed_str are allowed.')
exit(1)
}
cfg.set_output_type_from_str(format)
i++
}
'-inline-assets' {
cfg.inline_assets = true
}
'-l' {
cfg.show_loc = true
}
'-m' {
cfg.is_multi = true
}
'-o' {
opath := cmdline.option(current_args, '-o', '')
cfg.output_path = os.real_path(opath)
i++
}
'-s' {
cfg.inline_assets = true
cfg.serve_http = true
cfg.output_type = .html
}
'-r' {
cfg.include_readme = true
}
'-v' {
cfg.is_verbose = true
}
else {
cfg.input_path = arg
break
}
}
}
if cfg.input_path.len == 0 {
eprintln('vdoc: No input path found.')
exit(1)
}
is_path := cfg.input_path.ends_with('.v') || cfg.input_path.split(os.path_separator).len > 1 || cfg.input_path == '.'
if cfg.input_path == 'vlib' {
cfg.is_multi = true
cfg.input_path = os.join_path(os.base_dir(@VEXE), '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) eprintln(err)
exit(1) exit(1)
} }
config.src_path = mod_path cfg.input_path = mod_path
} }
config.generate_docs_from_file() cfg.generate_docs_from_file()
} }

19
cmd/v/help/doc.txt
View File

@ -1,8 +1,10 @@
Usage: Usage:
v doc [flags] module_name output_file[.json|.md|.html] v doc [flags] [module_name / folder / V file]
v doc [flags] path_to_source.v output_file[.json|.md|.html]
v doc [flags] ./directory output_file[.json|.md|.html] Examples:
v doc [flags] . output_file[.json|.md|.html] v doc os
v doc -o math.html math
v doc -m -f html vlib/
Generates the documentation of a given directory, module, or V source file Generates the documentation of a given directory, module, or V source file
and prints or saves them to its desired format. It can generate HTML, JSON, and prints or saves them to its desired format. It can generate HTML, JSON,
@ -10,7 +12,12 @@ or Markdown format.
Options: Options:
-all Includes private and public functions/methods/structs/consts/enums. -all Includes private and public functions/methods/structs/consts/enums.
-loc Show the locations of the generated signatures. (For plaintext only) -f Specifies the output format to be used.
-inline-assets
Embeds the contents of the CSS and JS assets into the webpage directly.
-l Show the locations of the generated signatures. (For plaintext only)
-m Generate docs for modules listed in that folder. -m Generate docs for modules listed in that folder.
-o Specifies the output file/folder path where to store the generated docs.
-s Serve HTML-generated docs via HTTP. -s Serve HTML-generated docs via HTTP.
-r Include README.md to docs if present. -r Include README.md to docs if present.
-v Enables verbose logging. For debugging purposes.

3
vlib/v/doc/doc.v
View File

@ -221,7 +221,7 @@ pub fn (mut d Doc) generate() ?bool {
content: 'module $module_name' content: 'module $module_name'
comment: '' comment: ''
} }
} else if file_ast.mod.name != module_name { } else if file_ast.mod.name != orig_mod_name {
continue continue
} }
stmts := file_ast.stmts stmts := file_ast.stmts
@ -257,6 +257,7 @@ pub fn (mut d Doc) generate() ?bool {
node.parent_type = parent_type node.parent_type = parent_type
} }
} }
if node.name.len == 0 && node.comment.len == 0 && node.content.len == 0 { continue }
d.contents << node d.contents << node
} }
if d.with_comments && (si - 1 >= 0 && stmts[si - 1] is ast.Comment) { if d.with_comments && (si - 1 >= 0 && stmts[si - 1] is ast.Comment) {

8
vlib/v/pref/pref.v
View File

@ -244,10 +244,6 @@ pub fn parse_args(args []string) (&Preferences, string) {
} }
'-o' { '-o' {
res.out_name = cmdline.option(current_args, '-o', '') res.out_name = cmdline.option(current_args, '-o', '')
if res.out_name.ends_with('.v') {
eprintln('Cannot save output binary in a .v file.')
exit(1)
}
i++ i++
} }
'-b' { '-b' {
@ -290,6 +286,10 @@ pub fn parse_args(args []string) (&Preferences, string) {
} }
} }
} }
if command != 'doc' && res.out_name.ends_with('.v') {
eprintln('Cannot save output binary in a .v file.')
exit(1)
}
if command.ends_with('.v') || os.exists(command) { if command.ends_with('.v') || os.exists(command) {
res.path = command res.path = command
} else if command == 'run' { } else if command == 'run' {