tools/check-md: allow directories as args and deprecate -all flag (#8582)

.github/workflows/docs_ci.yml

@@ -13,6 +13,6 @@ jobs:
     - name: Build V
       run: make
     - name: Check markdown line length & code examples
-      run: ./v run cmd/tools/check-md.v -hide-warnings -all
+      run: ./v check-md -hide-warnings .
     ## NB: -hide-warnings is used here, so that the output is less noisy,
     ## thus real errors are easier to spot.

TESTS.md

@@ -46,7 +46,7 @@ This is not required.
 
 Test all files in the current directory are formatted.
 
-* `v run cmd/tools/check-md.v -hide-warnings -all`
+* `v check-md -hide-warnings .`
 
 Ensure that all .md files in the project are formatted properly,
 and that the V code block examples in them can be compiled/formatted too.
@@ -83,5 +83,5 @@ It works, by running these in succession:
 * `v test-fmt`
 * `v build-tools`
 * `v build-examples`
-* `v run cmd/tools/check-md.v -hide-warnings -all`
+* `v check-md -hide-warnings .`
 * `v install nedpals.args`

cmd/tools/vcheck-md.v

@@ -1,9 +1,13 @@
+// Copyright (c) 2019-2021 Alexander Medvednikov. All rights reserved.
+// Use of this source code is governed by an MIT license
+// that can be found in the LICENSE file.
 module main
 
 import os
 import os.cmdline
 import rand
 import term
+import vhelp
 import v.pref
 
 const (
@@ -11,35 +15,19 @@ const (
 	term_colors          = term.can_show_color_on_stderr()
 	is_all               = '-all' in os.args
 	hide_warnings        = '-hide-warnings' in os.args
-	non_option_args      = cmdline.only_non_options(os.args[1..])
+	non_option_args      = cmdline.only_non_options(os.args[2..])
 )
 
-fn wprintln(s string) {
-	if !hide_warnings {
-		println(s)
-	}
-}
-
 fn main() {
-	if os.args.len == 1 {
+	if non_option_args.len == 0 || '-help' in os.args {
-		println('Usage: checks the passed markdown files for correct ```v ``` code blocks,
+		vhelp.show_topic('check-md')
-and for other style violations. like too long lines/links etc...
-a) `v run cmd/tools/check-md.v -all` - will check *all* .md files in the folders.
-b) `v run cmd/tools/check-md.v doc/docs.md` - will only check a single file.
-c) `v run cmd/tools/check-md.v -hide-warnings file.md` - same, but will not print warnings, only errors.
-
-NB: There are several special keywords, which you can put after the code fences for v.
-These are:
-	compile      - default, you do not need to specify it. cmd/tools/check-md.v compile the example.
-	ignore       - ignore the example, useful for examples that just use the syntax highlighting
-	failcompile  - known failing compilation. Useful for examples demonstrating compiler errors.
-	oksyntax     - it should parse, it may not compile. Useful for partial examples.
-	badsyntax    - known bad syntax, it should not even parse
-	wip          - like ignore; a planned feature; easy to search.
-')
 		exit(0)
 	}
-	files_paths := if is_all { md_file_paths() } else { non_option_args }
+	if is_all {
+		println('´-all´ flag is deprecated. Please use ´v check-md .´ instead.')
+		exit(1)
+	}
+	mut files_paths := non_option_args.clone()
 	mut warnings := 0
 	mut errors := 0
 	mut oks := 0
@@ -47,7 +35,12 @@ These are:
 	if term_colors {
 		os.setenv('VCOLORS', 'always', true)
 	}
-	for file_path in files_paths {
+	for i := 0; i < files_paths.len; i++ {
+		file_path := files_paths[i]
+		if os.is_dir(file_path) {
+			files_paths << md_file_paths(file_path)
+			continue
+		}
 		real_path := os.real_path(file_path)
 		lines := os.read_lines(real_path) or {
 			println('"$file_path" does not exist')
@@ -57,31 +50,31 @@ These are:
 		mut mdfile := MDFile{
 			path: file_path
 		}
-		for i, line in lines {
+		for j, line in lines {
 			if line.len > too_long_line_length {
 				if mdfile.state == .vexample {
-					wprintln(wline(file_path, i, line.len, 'long V example line'))
+					wprintln(wline(file_path, j, line.len, 'long V example line'))
 					wprintln(line)
 					warnings++
 				} else if mdfile.state == .codeblock {
-					wprintln(wline(file_path, i, line.len, 'long code block line'))
+					wprintln(wline(file_path, j, line.len, 'long code block line'))
 					wprintln(line)
 					warnings++
 				} else if line.starts_with('|') {
-					wprintln(wline(file_path, i, line.len, 'long table'))
+					wprintln(wline(file_path, j, line.len, 'long table'))
 					wprintln(line)
 					warnings++
 				} else if line.contains('https') {
-					wprintln(wline(file_path, i, line.len, 'long link'))
+					wprintln(wline(file_path, j, line.len, 'long link'))
 					wprintln(line)
 					warnings++
 				} else {
-					eprintln(eline(file_path, i, line.len, 'line too long'))
+					eprintln(eline(file_path, j, line.len, 'line too long'))
 					eprintln(line)
 					errors++
 				}
 			}
-			mdfile.parse_line(i, line)
+			mdfile.parse_line(j, line)
 		}
 		all_md_files << mdfile
 	}
@@ -90,7 +83,6 @@ These are:
 		errors += new_errors
 		oks += new_oks
 	}
-	// println('all_md_files: $all_md_files')
 	if warnings > 0 || errors > 0 || oks > 0 {
 		println('\nWarnings: $warnings | Errors: $errors | OKs: $oks')
 	}
@@ -99,14 +91,11 @@ These are:
 	}
 }
 
-fn md_file_paths() []string {
+fn md_file_paths(dir string) []string {
 	mut files_to_check := []string{}
-	md_files := os.walk_ext('.', '.md')
+	md_files := os.walk_ext(dir, '.md')
 	for file in md_files {
-		if file.starts_with('./thirdparty') {
+		if file.contains_any_substr(['/thirdparty/', 'CHANGELOG']) {
-			continue
-		}
-		if file.contains('CHANGELOG') {
 			continue
 		}
 		files_to_check << file
@@ -114,6 +103,12 @@ fn md_file_paths() []string {
 	return files_to_check
 }
 
+fn wprintln(s string) {
+	if !hide_warnings {
+		println(s)
+	}
+}
+
 fn ftext(s string, cb fn (string) string) string {
 	if term_colors {
 		return cb(s)

cmd/tools/vtest-all.v

@@ -78,7 +78,7 @@ fn get_all_commands() []Command {
 		okmsg: 'All examples can be compiled.'
 	}
 	res << Command{
-		line: '$vexe run cmd/tools/check-md.v -hide-warnings -all'
+		line: '$vexe check-md -hide-warnings .'
 		label: 'Check ```v ``` code examples and formatting of .MD files...'
 		okmsg: 'All .md files look good.'
 	}

cmd/v/help/check-md.txt

@@ -0,0 +1,21 @@
+check-md is a tool to check the passed markdown files for correct ```v ``` code blocks
+and other style violations like too long lines/links etc...
+
+Usage:
+	a) `v check-md [flags] <...files>` - Check the given .md files.
+	b) `v check-md [flags] <...dirs>`  - Check *all* files in the given directories.
+	Note: You can also combine files and directories.
+
+Flags:
+	-hide-warnings    Do not print warnings, only errors.
+
+NB: There are several special keywords, which you can put after the code fences for v.
+These are:
+	compile      - Default, can be omitted. The example will be compiled and formatting is verified.
+	live         - Compile hot reload examples with the ´-live´ flag set and verify formatting.
+	ignore       - Ignore the example, useful for examples that just use the syntax highlighting
+	failcompile  - Known failing compilation. Useful for examples demonstrating compiler errors.
+	oksyntax     - Should parse and be formatted but may not compile. Useful for partial examples.
+	badsyntax    - Known bad syntax, it should not even parse.
+	wip          - Like ignore; a planned feature; easy to search.
+	nofmt        - Disable fmt verification for individual code blocks.

cmd/v/help/default.txt

@@ -35,7 +35,7 @@ V supports the following commands:
    list              List all installed modules.
    outdated          Show installed modules that need updates.
 * Others:
-   doctor            Display some usefull info about your system to help reporting bugs
+   doctor            Display some usefull info about your system to help reporting bugs.
    translate         Translate C code to V (coming soon in 0.3).
    tracev            Produce a tracing version of the v compiler.
                      Use `tracev yourfile.v` when the compiler panics.
@@ -45,4 +45,4 @@ Use "v help <command>" for more information about a command, example: `v help bu
 Use "v help other" to see less frequently used commands.
 
 Note: Help is required to write more help topics.
-Only build, doc, fmt, run, test, search, install, remove, update, bin2v are properly documented currently.
+Only build, doc, fmt, run, test, search, install, remove, update, bin2v, check-md are properly documented currently.

cmd/v/help/other.txt

@@ -8,6 +8,8 @@ but which are used less frequently by users:
    build-tools        Test if all tools can be built.
    build-vbinaries    Test if V can be built with different configuration.
 
+   check-md          Check that V examples in markdown files are formatted and can compile.
+
    test-all           Run most checks, that the CI does locally.
                       It may take over 2 minutes, and it needs internet connectivity too,
                       because it tries to also verify that `v install` works.

cmd/v/v.v

@@ -27,6 +27,7 @@ const (
 		'test-compiler', /* deprecated by test-self */
 		'test-compiler-full', /* deprecated by test-self */
 		'test-cleancode',
+		'check-md',
 		'repl',
 		'complete',
 		'build-tools',

doc/docs.md

@@ -136,8 +136,8 @@ For more details and troubleshooting, please visit the [vab GitHub repository](h
 
 <!--
 NB: there are several special keywords, which you can put after the code fences for v:
-compile, ignore, failcompile, oksyntax, badsyntax, wip
+compile, live, ignore, failcompile, oksyntax, badsyntax, wip, nofmt
-For more details, do: `v run cmd/tools/check-md.v`
+For more details, do: `v check-md`
 -->
 
 ## Hello World