From 76ea3e7b41849362b69eac153350360e2ec73d37 Mon Sep 17 00:00:00 2001 From: Lukas Neubert Date: Fri, 5 Feb 2021 16:46:20 +0100 Subject: [PATCH] tools/check-md: allow directories as args and deprecate -all flag (#8582) --- .github/workflows/docs_ci.yml | 2 +- TESTS.md | 14 ++--- cmd/tools/{check-md.v => vcheck-md.v} | 73 +++++++++++++-------------- cmd/tools/vtest-all.v | 2 +- cmd/v/help/check-md.txt | 21 ++++++++ cmd/v/help/default.txt | 4 +- cmd/v/help/other.txt | 2 + cmd/v/v.v | 1 + doc/docs.md | 4 +- 9 files changed, 71 insertions(+), 52 deletions(-) rename cmd/tools/{check-md.v => vcheck-md.v} (79%) create mode 100644 cmd/v/help/check-md.txt diff --git a/.github/workflows/docs_ci.yml b/.github/workflows/docs_ci.yml index 725a46a786..a671ab6675 100644 --- a/.github/workflows/docs_ci.yml +++ b/.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. diff --git a/TESTS.md b/TESTS.md index 94b6e25207..ff39c5f7ed 100644 --- a/TESTS.md +++ b/TESTS.md @@ -1,15 +1,15 @@ # Automated tests -TLDR: run `v test-all` locally, after making your changes, +TLDR: run `v test-all` locally, after making your changes, and before submitting PRs. ## Notes In the `v` repo there are several different tests. The main types are: -* `_test.v` tests - check that `test_` functions succeed. These can be +* `_test.v` tests - check that `test_` functions succeed. These can be run per directory or individually. -* `.out` tests - run a `.vv` file and check the output matches the -contents of the `.out` file with the same base name. This is +* `.out` tests - run a `.vv` file and check the output matches the +contents of the `.out` file with the same base name. This is particularly useful for checking that errors are printed. Tip: use `v -cc tcc` when compiling tests for speed. @@ -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. @@ -75,7 +75,7 @@ This runs tests for: ## `v test-all` Test and build *everything*. Usefull to verify *locally*, that the CI will -most likely pass. Slowest, but most comprehensive. +most likely pass. Slowest, but most comprehensive. It works, by running these in succession: * `v test-cleancode` @@ -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` diff --git a/cmd/tools/check-md.v b/cmd/tools/vcheck-md.v similarity index 79% rename from cmd/tools/check-md.v rename to cmd/tools/vcheck-md.v index 18f9b79c94..6f7ea1c8e8 100644 --- a/cmd/tools/check-md.v +++ b/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 { - println('Usage: checks the passed markdown files for correct ```v ``` code blocks, -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. -') + if non_option_args.len == 0 || '-help' in os.args { + vhelp.show_topic('check-md') 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') { - continue - } - if file.contains('CHANGELOG') { + if file.contains_any_substr(['/thirdparty/', '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) diff --git a/cmd/tools/vtest-all.v b/cmd/tools/vtest-all.v index 293ba5fcd6..45c30db5ed 100644 --- a/cmd/tools/vtest-all.v +++ b/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.' } diff --git a/cmd/v/help/check-md.txt b/cmd/v/help/check-md.txt new file mode 100644 index 0000000000..29a6a36d68 --- /dev/null +++ b/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. diff --git a/cmd/v/help/default.txt b/cmd/v/help/default.txt index 0cd163e6ec..ab7f6249c2 100644 --- a/cmd/v/help/default.txt +++ b/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 " 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. diff --git a/cmd/v/help/other.txt b/cmd/v/help/other.txt index a8a7921926..f329baaf83 100644 --- a/cmd/v/help/other.txt +++ b/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. diff --git a/cmd/v/v.v b/cmd/v/v.v index 2281593cb3..ef043eb9b0 100644 --- a/cmd/v/v.v +++ b/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', diff --git a/doc/docs.md b/doc/docs.md index 9ea863f530..0ed2267f6c 100644 --- a/doc/docs.md +++ b/doc/docs.md @@ -136,8 +136,8 @@ For more details and troubleshooting, please visit the [vab GitHub repository](h ## Hello World