550 lines
14 KiB
V
550 lines
14 KiB
V
module main
|
|
|
|
import markdown
|
|
import os
|
|
import os.cmdline
|
|
import time
|
|
import strings
|
|
import sync
|
|
import runtime
|
|
import v.doc
|
|
import v.pref
|
|
import v.vmod
|
|
import json
|
|
import term
|
|
|
|
const (
|
|
allowed_formats = ['md', 'markdown', 'json', 'text', 'stdout', 'html', 'htm']
|
|
vexe = pref.vexe_path()
|
|
vroot = os.dir(vexe)
|
|
tabs = ['\t\t', '\t\t\t\t\t\t', '\t\t\t\t\t\t\t']
|
|
)
|
|
|
|
enum OutputType {
|
|
unset
|
|
html
|
|
markdown
|
|
json
|
|
plaintext
|
|
stdout
|
|
}
|
|
|
|
struct VDoc {
|
|
cfg Config [required]
|
|
mut:
|
|
docs []doc.Doc
|
|
assets map[string]string
|
|
manifest vmod.Manifest
|
|
search_index []string
|
|
search_data []SearchResult
|
|
search_module_index []string // search results are split into a module part and the rest
|
|
search_module_data []SearchModuleResult
|
|
}
|
|
|
|
struct Config {
|
|
mut:
|
|
pub_only bool = true
|
|
show_loc bool // for plaintext
|
|
is_color bool
|
|
is_multi bool
|
|
is_vlib bool
|
|
is_verbose bool
|
|
include_readme bool
|
|
include_examples bool = true
|
|
include_comments bool // for plaintext
|
|
inline_assets bool
|
|
theme_dir string = default_theme
|
|
no_timestamp bool
|
|
output_path string
|
|
output_type OutputType = .unset
|
|
input_path string
|
|
symbol_name string
|
|
platform doc.Platform
|
|
}
|
|
|
|
//
|
|
struct Output {
|
|
mut:
|
|
path string
|
|
typ OutputType = .unset
|
|
}
|
|
|
|
struct ParallelDoc {
|
|
d doc.Doc
|
|
out Output
|
|
}
|
|
|
|
fn (vd VDoc) gen_json(d doc.Doc) string {
|
|
cfg := vd.cfg
|
|
mut jw := strings.new_builder(200)
|
|
comments := if cfg.include_examples {
|
|
d.head.merge_comments()
|
|
} else {
|
|
d.head.merge_comments_without_examples()
|
|
}
|
|
jw.write_string('{"module_name":"$d.head.name","description":"${escape(comments)}","contents":')
|
|
jw.write_string(json.encode(d.contents.keys().map(d.contents[it])))
|
|
jw.write_string(',"generator":"vdoc","time_generated":"$d.time_generated.str()"}')
|
|
return jw.str()
|
|
}
|
|
|
|
fn (vd VDoc) gen_plaintext(d doc.Doc) string {
|
|
cfg := vd.cfg
|
|
mut pw := strings.new_builder(200)
|
|
if cfg.is_color {
|
|
content_arr := d.head.content.split(' ')
|
|
pw.writeln('${term.bright_blue(content_arr[0])} ${term.green(content_arr[1])}\n')
|
|
} else {
|
|
pw.writeln('$d.head.content\n')
|
|
}
|
|
if cfg.include_comments {
|
|
comments := if cfg.include_examples {
|
|
d.head.merge_comments()
|
|
} else {
|
|
d.head.merge_comments_without_examples()
|
|
}
|
|
if comments.trim_space().len > 0 {
|
|
pw.writeln(indent(comments))
|
|
}
|
|
}
|
|
vd.write_plaintext_content(d.contents.arr(), mut pw)
|
|
return pw.str()
|
|
}
|
|
|
|
fn indent(s string) string {
|
|
return ' ' + s.replace('\n', '\n ')
|
|
}
|
|
|
|
fn (vd VDoc) write_plaintext_content(contents []doc.DocNode, mut pw strings.Builder) {
|
|
cfg := vd.cfg
|
|
for cn in contents {
|
|
if cn.content.len > 0 {
|
|
if cfg.is_color {
|
|
pw.writeln(color_highlight(cn.content, vd.docs[0].table))
|
|
} else {
|
|
pw.writeln(cn.content)
|
|
}
|
|
if cn.comments.len > 0 && cfg.include_comments {
|
|
comments := cn.merge_comments_without_examples()
|
|
pw.writeln(indent(comments.trim_space()))
|
|
if cfg.include_examples {
|
|
examples := cn.examples()
|
|
for ex in examples {
|
|
pw.write_string(' Example: ')
|
|
mut fex := ex
|
|
if ex.index_byte(`\n`) >= 0 {
|
|
// multi-line example
|
|
pw.write_byte(`\n`)
|
|
fex = indent(ex)
|
|
}
|
|
if cfg.is_color {
|
|
fex = color_highlight(fex, vd.docs[0].table)
|
|
}
|
|
pw.writeln(fex)
|
|
}
|
|
}
|
|
}
|
|
if cfg.show_loc {
|
|
pw.writeln('Location: $cn.file_path:${cn.pos.line_nr + 1}\n')
|
|
}
|
|
}
|
|
vd.write_plaintext_content(cn.children, mut pw)
|
|
}
|
|
}
|
|
|
|
fn (vd VDoc) render_doc(d doc.Doc, out Output) (string, string) {
|
|
name := vd.get_file_name(d.head.name, out)
|
|
output := match out.typ {
|
|
.html { vd.gen_html(d) }
|
|
.markdown { vd.gen_markdown(d, true) }
|
|
.json { vd.gen_json(d) }
|
|
else { vd.gen_plaintext(d) }
|
|
}
|
|
return name, output
|
|
}
|
|
|
|
// get_file_name returns the final file name from a module name
|
|
fn (vd VDoc) get_file_name(mod string, out Output) string {
|
|
cfg := vd.cfg
|
|
mut name := mod
|
|
// since builtin is generated first, ignore it
|
|
if (cfg.is_vlib && mod == 'builtin' && !cfg.include_readme) || mod == 'README' {
|
|
name = 'index'
|
|
} else if !cfg.is_multi && !os.is_dir(out.path) {
|
|
name = os.file_name(out.path)
|
|
}
|
|
if name == '' {
|
|
name = 'index'
|
|
}
|
|
name = name + match out.typ {
|
|
.html { '.html' }
|
|
.markdown { '.md' }
|
|
.json { '.json' }
|
|
else { '.txt' }
|
|
}
|
|
return name
|
|
}
|
|
|
|
fn (vd VDoc) work_processor(mut work sync.Channel, mut wg sync.WaitGroup) {
|
|
for {
|
|
mut pdoc := ParallelDoc{}
|
|
if !work.pop(&pdoc) {
|
|
break
|
|
}
|
|
file_name, content := vd.render_doc(pdoc.d, pdoc.out)
|
|
output_path := os.join_path(pdoc.out.path, file_name)
|
|
println('Generating $pdoc.out.typ in "$output_path"')
|
|
os.write_file(output_path, content) or { panic(err) }
|
|
}
|
|
wg.done()
|
|
}
|
|
|
|
fn (vd VDoc) render_parallel(out Output) {
|
|
vjobs := runtime.nr_jobs()
|
|
mut work := sync.new_channel<ParallelDoc>(u32(vd.docs.len))
|
|
mut wg := sync.new_waitgroup()
|
|
for i in 0 .. vd.docs.len {
|
|
p_doc := ParallelDoc{vd.docs[i], out}
|
|
work.push(&p_doc)
|
|
}
|
|
work.close()
|
|
wg.add(vjobs)
|
|
for _ in 0 .. vjobs {
|
|
go vd.work_processor(mut work, mut wg)
|
|
}
|
|
wg.wait()
|
|
}
|
|
|
|
fn (vd VDoc) render(out Output) map[string]string {
|
|
mut docs := map[string]string{}
|
|
for doc in vd.docs {
|
|
name, output := vd.render_doc(doc, out)
|
|
docs[name] = output.trim_space()
|
|
}
|
|
vd.vprintln('Rendered: ' + docs.keys().str())
|
|
return docs
|
|
}
|
|
|
|
fn (vd VDoc) get_readme(path string) string {
|
|
mut fname := ''
|
|
for name in ['readme', 'README'] {
|
|
if os.exists(os.join_path(path, '${name}.md')) {
|
|
fname = name
|
|
break
|
|
}
|
|
}
|
|
if fname == '' {
|
|
return ''
|
|
}
|
|
readme_path := os.join_path(path, '${fname}.md')
|
|
vd.vprintln('Reading README file from $readme_path')
|
|
readme_contents := os.read_file(readme_path) or { '' }
|
|
return readme_contents
|
|
}
|
|
|
|
fn (vd VDoc) emit_generate_err(err IError) {
|
|
cfg := vd.cfg
|
|
mut err_msg := err.msg
|
|
if err.code == 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 vd VDoc) generate_docs_from_file() {
|
|
cfg := vd.cfg
|
|
mut out := Output{
|
|
path: cfg.output_path
|
|
typ: cfg.output_type
|
|
}
|
|
if out.path.len == 0 {
|
|
if cfg.output_type == .unset {
|
|
out.typ = .stdout
|
|
} else {
|
|
vd.vprintln('No output path has detected. Using input path instead.')
|
|
out.path = cfg.input_path
|
|
}
|
|
} else if out.typ == .unset {
|
|
vd.vprintln('Output path detected. Identifying output type..')
|
|
ext := os.file_ext(out.path)
|
|
out.typ = set_output_type_from_str(ext.all_after('.'))
|
|
}
|
|
if cfg.include_readme && out.typ !in [.html, .stdout] {
|
|
eprintln('vdoc: Including README.md for doc generation is supported on HTML output, or when running directly in the terminal.')
|
|
exit(1)
|
|
}
|
|
dir_path := if cfg.is_vlib {
|
|
vroot
|
|
} else if os.is_dir(cfg.input_path) {
|
|
cfg.input_path
|
|
} else {
|
|
os.dir(cfg.input_path)
|
|
}
|
|
manifest_path := os.join_path(dir_path, 'v.mod')
|
|
if os.exists(manifest_path) {
|
|
vd.vprintln('Reading v.mod info from $manifest_path')
|
|
if manifest := vmod.from_file(manifest_path) {
|
|
vd.manifest = manifest
|
|
}
|
|
}
|
|
if cfg.include_readme {
|
|
readme_contents := vd.get_readme(dir_path)
|
|
comment := doc.DocComment{
|
|
text: readme_contents
|
|
}
|
|
if out.typ == .stdout {
|
|
println(markdown.to_plain(readme_contents))
|
|
} else if out.typ == .html && cfg.is_multi {
|
|
vd.docs << doc.Doc{
|
|
head: doc.DocNode{
|
|
name: 'README'
|
|
comments: [comment]
|
|
}
|
|
time_generated: time.now()
|
|
}
|
|
}
|
|
}
|
|
dirs := if cfg.is_multi { get_modules_list(cfg.input_path, []string{}) } else { [
|
|
cfg.input_path,
|
|
] }
|
|
for dirpath in dirs {
|
|
vd.vprintln('Generating $out.typ docs for "$dirpath"')
|
|
mut dcs := doc.generate(dirpath, cfg.pub_only, true, cfg.platform, cfg.symbol_name) or {
|
|
vd.emit_generate_err(err)
|
|
exit(1)
|
|
}
|
|
if dcs.contents.len == 0 {
|
|
continue
|
|
}
|
|
if cfg.is_multi || (!cfg.is_multi && cfg.include_readme) {
|
|
readme_contents := vd.get_readme(dirpath)
|
|
comment := doc.DocComment{
|
|
text: readme_contents
|
|
}
|
|
dcs.head.comments = [comment]
|
|
}
|
|
if cfg.pub_only {
|
|
for name, dc in dcs.contents {
|
|
dcs.contents[name].content = dc.content.all_after('pub ')
|
|
for i, cc in dc.children {
|
|
dcs.contents[name].children[i].content = cc.content.all_after('pub ')
|
|
}
|
|
}
|
|
}
|
|
vd.docs << dcs
|
|
}
|
|
// Important. Let builtin be in the top of the module list
|
|
// if we are generating docs for vlib.
|
|
if cfg.is_vlib {
|
|
mut docs := vd.docs.filter(it.head.name == 'builtin')
|
|
docs << vd.docs.filter(it.head.name != 'builtin')
|
|
vd.docs = docs
|
|
}
|
|
if dirs.len == 0 && cfg.is_multi {
|
|
eprintln('vdoc: -m requires at least 1 module folder')
|
|
exit(1)
|
|
}
|
|
vd.vprintln('Rendering docs...')
|
|
if out.path.len == 0 || out.path == 'stdout' {
|
|
if out.typ == .html {
|
|
vd.render_static_html(out)
|
|
}
|
|
outputs := vd.render(out)
|
|
if outputs.len == 0 {
|
|
if dirs.len == 0 {
|
|
eprintln('vdoc: No documentation found')
|
|
} else {
|
|
eprintln('vdoc: No documentation found for ${dirs[0]}')
|
|
}
|
|
exit(1)
|
|
} else {
|
|
first := outputs.keys()[0]
|
|
println(outputs[first])
|
|
}
|
|
} else {
|
|
if !os.exists(out.path) {
|
|
os.mkdir_all(out.path) or { panic(err) }
|
|
} else if !os.is_dir(out.path) {
|
|
out.path = os.real_path('.')
|
|
}
|
|
if cfg.is_multi {
|
|
out.path = os.join_path(out.path, '_docs')
|
|
if !os.exists(out.path) {
|
|
os.mkdir(out.path) or { panic(err) }
|
|
} else {
|
|
for fname in css_js_assets {
|
|
existing_asset_path := os.join_path(out.path, fname)
|
|
if os.exists(existing_asset_path) {
|
|
os.rm(existing_asset_path) or { panic(err) }
|
|
}
|
|
}
|
|
}
|
|
}
|
|
if out.typ == .html {
|
|
vd.render_static_html(out)
|
|
}
|
|
vd.render_parallel(out)
|
|
if out.typ == .html {
|
|
println('Creating search index...')
|
|
vd.collect_search_index(out)
|
|
vd.render_search_index(out)
|
|
// move favicons to target directory
|
|
println('Copying favicons...')
|
|
|
|
favicons_path := os.join_path(cfg.theme_dir, 'favicons')
|
|
|
|
favicons := os.ls(favicons_path) or { panic(err) }
|
|
for favicon in favicons {
|
|
favicon_path := os.join_path(favicons_path, favicon)
|
|
destination_path := os.join_path(out.path, favicon)
|
|
os.cp(favicon_path, destination_path) or { panic(err) }
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
fn (vd VDoc) vprintln(str string) {
|
|
if vd.cfg.is_verbose {
|
|
println('vdoc: $str')
|
|
}
|
|
}
|
|
|
|
fn parse_arguments(args []string) Config {
|
|
mut cfg := Config{}
|
|
cfg.is_color = term.can_show_color_on_stdout()
|
|
for i := 0; i < args.len; i++ {
|
|
arg := args[i]
|
|
current_args := args[i..]
|
|
match arg {
|
|
'-all' {
|
|
cfg.pub_only = false
|
|
}
|
|
'-f' {
|
|
format := cmdline.option(current_args, '-f', '')
|
|
if format !in allowed_formats {
|
|
allowed_str := allowed_formats.join(', ')
|
|
eprintln('vdoc: "$format" is not a valid format. Only $allowed_str are allowed.')
|
|
exit(1)
|
|
}
|
|
cfg.output_type = set_output_type_from_str(format)
|
|
i++
|
|
}
|
|
'-color' {
|
|
cfg.is_color = true
|
|
}
|
|
'-no-color' {
|
|
cfg.is_color = false
|
|
}
|
|
'-inline-assets' {
|
|
cfg.inline_assets = true
|
|
}
|
|
'-theme-dir' {
|
|
cfg.theme_dir = cmdline.option(current_args, '-theme-dir', default_theme)
|
|
}
|
|
'-l' {
|
|
cfg.show_loc = true
|
|
}
|
|
'-comments' {
|
|
cfg.include_comments = true
|
|
}
|
|
'-m' {
|
|
cfg.is_multi = true
|
|
}
|
|
'-o' {
|
|
opath := cmdline.option(current_args, '-o', '')
|
|
cfg.output_path = if opath == 'stdout' { opath } else { os.real_path(opath) }
|
|
i++
|
|
}
|
|
'-os' {
|
|
platform_str := cmdline.option(current_args, '-os', '')
|
|
if platform_str == 'cross' {
|
|
eprintln('`v doc -os cross` is not supported yet.')
|
|
exit(1)
|
|
}
|
|
selected_platform := doc.platform_from_string(platform_str) or {
|
|
eprintln(err.msg)
|
|
exit(1)
|
|
}
|
|
cfg.platform = selected_platform
|
|
i++
|
|
}
|
|
'-no-timestamp' {
|
|
cfg.no_timestamp = true
|
|
}
|
|
'-no-examples' {
|
|
cfg.include_examples = false
|
|
}
|
|
'-readme' {
|
|
cfg.include_readme = true
|
|
}
|
|
'-v' {
|
|
cfg.is_verbose = true
|
|
}
|
|
else {
|
|
if cfg.input_path.len < 1 {
|
|
cfg.input_path = arg
|
|
} else if !cfg.is_multi {
|
|
// Symbol name filtering should not be enabled
|
|
// in multi-module documentation mode.
|
|
cfg.symbol_name = arg
|
|
}
|
|
if i == args.len - 1 {
|
|
break
|
|
}
|
|
}
|
|
}
|
|
}
|
|
// Correct from configuration from user input
|
|
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 {
|
|
cfg.input_path = cfg.input_path.replace('\\', os.path_separator)
|
|
}
|
|
is_path := cfg.input_path.ends_with('.v') || cfg.input_path.split(os.path_separator).len > 1
|
|
|| cfg.input_path == '.'
|
|
if cfg.input_path.trim_right('/') == 'vlib' {
|
|
cfg.is_vlib = true
|
|
cfg.is_multi = true
|
|
cfg.input_path = os.join_path(vroot, 'vlib')
|
|
} else if !is_path {
|
|
// TODO vd.vprintln('Input "$cfg.input_path" is not a valid path. Looking for modules named "$cfg.input_path"...')
|
|
mod_path := doc.lookup_module(cfg.input_path) or {
|
|
eprintln('vdoc: $err')
|
|
exit(1)
|
|
}
|
|
cfg.input_path = mod_path
|
|
}
|
|
return cfg
|
|
}
|
|
|
|
fn main() {
|
|
if os.args.len < 2 || '-h' in os.args || '-help' in os.args || '--help' in os.args
|
|
|| os.args[1..] == ['doc', 'help'] {
|
|
os.system('${os.quoted_path(vexe)} help doc')
|
|
exit(0)
|
|
}
|
|
args := os.args[2..].clone()
|
|
cfg := parse_arguments(args)
|
|
if cfg.input_path.len == 0 {
|
|
eprintln('vdoc: No input path found.')
|
|
exit(1)
|
|
}
|
|
// Config is immutable from this point on
|
|
mut vd := VDoc{
|
|
cfg: cfg
|
|
manifest: vmod.Manifest{
|
|
repo_url: ''
|
|
}
|
|
}
|
|
vd.vprintln('Setting output type to "$cfg.output_type"')
|
|
vd.generate_docs_from_file()
|
|
}
|