From df4165c7ee9f986bc7dcc955b6ae4cdc0ea31203 Mon Sep 17 00:00:00 2001 From: Lukas Neubert Date: Wed, 18 Nov 2020 18:28:28 +0100 Subject: [PATCH] docs_ci: check all md files except thirdparty (#6855) --- .github/workflows/ci.yml | 8 +- .github/workflows/docs_ci.yml | 16 +- README.md | 10 +- cmd/tools/check-md.v | 47 +++++- examples/game_of_life/README.md | 4 +- .../building-a-simple-web-blog-with-vweb.md | 26 +-- vlib/encoding/csv/{readme.md => README.md} | 0 vlib/eventbus/README.md | 29 ++-- vlib/net/html/README.md | 59 ++++--- vlib/pg/{readme.md => README.md} | 0 vlib/rand/README.md | 31 +++- vlib/regex/README.md | 153 +++++++++++------- vlib/sqlite/{readme.md => README.md} | 0 vlib/strconv/format.md | 36 +++-- vlib/term/README.md | 25 +-- vlib/term/ui/README.md | 68 +++++--- vlib/vweb/README.md | 6 +- vlib/vweb/tmpl/README.md | 21 ++- vlib/x/json2/README.md | 52 +++--- vlib/x/websocket/tests/autobahn/README.md | 3 +- 20 files changed, 373 insertions(+), 221 deletions(-) rename vlib/encoding/csv/{readme.md => README.md} (100%) rename vlib/pg/{readme.md => README.md} (100%) rename vlib/sqlite/{readme.md => README.md} (100%) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index dcfae7ff10..eec4cf364a 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -3,14 +3,10 @@ name: CI on: push: paths-ignore: - - "doc/**" - - "CHANGELOG.md" - - "CONTRIBUTING.md" + - "**.md" pull_request: paths-ignore: - - "doc/**" - - "CHANGELOG.md" - - "CONTRIBUTING.md" + - "**.md" jobs: code-formatting: diff --git a/.github/workflows/docs_ci.yml b/.github/workflows/docs_ci.yml index f94d24cb52..682ad26f59 100644 --- a/.github/workflows/docs_ci.yml +++ b/.github/workflows/docs_ci.yml @@ -3,23 +3,21 @@ name: Docs CI on: push: paths: + - ".github/workflows/docs_ci.yml" - "cmd/tools/check-md.v" - - "doc/**" - - "CHANGELOG.md" - - "CONTRIBUTING.md" + - "**.md" pull_request: paths: + - ".github/workflows/docs_ci.yml" - "cmd/tools/check-md.v" - - "doc/**" - - "CHANGELOG.md" - - "CONTRIBUTING.md" + - "**.md" jobs: - docs-line-len-check: + check-markdown: runs-on: ubuntu-18.04 steps: - uses: actions/checkout@v2 - name: Build V run: make - - name: Check docs line length & code examples - run: ./v run cmd/tools/check-md.v doc/docs.md doc/upcoming.md CHANGELOG.md CONTRIBUTING.md + - name: Check markdown line length & code examples + run: ./v run cmd/tools/check-md.v -all diff --git a/README.md b/README.md index 30779932b5..92ccc4d692 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,8 @@ ## Key Features of V - Simplicity: the language can be learned in less than an hour -- Fast compilation: ≈80k loc/s with a Clang backend, ≈1 million loc/s with x64 and tcc backends *(Intel i5-7500, SSD, no optimization)* +- Fast compilation: ≈80k loc/s with a Clang backend, + ≈1 million loc/s with x64 and tcc backends *(Intel i5-7500, SSD, no optimization)* - Easy to develop: V compiles itself in less than a second - Performance: as fast as C (V's main backend compiles to human readable C) - Safety: no null, no globals, no undefined behavior, immutability by default @@ -80,7 +81,8 @@ v up ### C compiler -It's recommended to use Clang or GCC or Visual Studio. If you are doing development, you most likely already have one of those installed. +It's recommended to use Clang or GCC or Visual Studio. +If you are doing development, you most likely already have one of those installed. Otherwise, follow these instructions: @@ -88,7 +90,9 @@ Otherwise, follow these instructions: - [Installing a C compiler on Windows](https://github.com/vlang/v/wiki/Installing-a-C-compiler-on-Windows) -However, if none is found when running `make` on Linux or Windows, TCC would be downloaded and set as an alternative C backend. It's very lightweight (several MB) so this shouldn't take too long. +However, if none is found when running `make` on Linux or Windows, +TCC would be downloaded and set as an alternative C backend. +It's very lightweight (several MB) so this shouldn't take too long. ### Symlinking diff --git a/cmd/tools/check-md.v b/cmd/tools/check-md.v index f54349dd28..675fd19e8c 100644 --- a/cmd/tools/check-md.v +++ b/cmd/tools/check-md.v @@ -11,7 +11,7 @@ const ( ) fn main() { - files_paths := os.args[1..] + files_paths := if '-all' in os.args { md_file_paths() } else { os.args[1..] } mut warnings := 0 mut errors := 0 mut oks := 0 @@ -28,7 +28,13 @@ fn main() { } for i, line in lines { if line.len > too_long_line_length { - if line.starts_with('|') { + if mdfile.state == .vexample { + println(wline(file_path, i, line.len, 'long V example line')) + warnings++ + } else if mdfile.state == .codeblock { + println(wline(file_path, i, line.len, 'long code block line')) + warnings++ + } else if line.starts_with('|') { println(wline(file_path, i, line.len, 'long table')) warnings++ } else if line.contains('https') { @@ -57,6 +63,18 @@ fn main() { } } +fn md_file_paths() []string { + mut files_to_check := []string{} + md_files := os.walk_ext('.', '.md') + for file in md_files { + if file.starts_with('./thirdparty') { + continue + } + files_to_check << file + } + return files_to_check +} + fn ftext(s string, cb fn (string) string) string { if term_colors { return cb(s) @@ -100,6 +118,7 @@ mut: enum MDFileParserState { markdown vexample + codeblock } struct MDFile { @@ -125,12 +144,24 @@ fn (mut f MDFile) parse_line(lnumber int, line string) { } return } - if line.starts_with('```') && f.state == .vexample { - f.state = .markdown - f.current.eline = lnumber - f.examples << f.current - f.current = VCodeExample{} - return + if line.starts_with('```') { + match f.state { + .vexample { + f.state = .markdown + f.current.eline = lnumber + f.examples << f.current + f.current = VCodeExample{} + return + } + .codeblock { + f.state = .markdown + return + } + .markdown { + f.state = .codeblock + return + } + } } if f.state == .vexample { f.current.text << line diff --git a/examples/game_of_life/README.md b/examples/game_of_life/README.md index 3234a9c46d..02969ff814 100644 --- a/examples/game_of_life/README.md +++ b/examples/game_of_life/README.md @@ -3,10 +3,8 @@ ![](https://github.com/fuyutarow/Conways-Game-of-Life-with-Vlang/raw/master/v-gun.gif) -```v +``` v run life.v ``` Created by fuyutarow: https://github.com/fuyutarow/Conways-Game-of-Life-with-Vlang - - diff --git a/tutorials/building-a-simple-web-blog-with-vweb.md b/tutorials/building-a-simple-web-blog-with-vweb.md index f1688cb82c..045d53bfdf 100644 --- a/tutorials/building-a-simple-web-blog-with-vweb.md +++ b/tutorials/building-a-simple-web-blog-with-vweb.md @@ -95,7 +95,7 @@ As you can see, there are no routing rules. The `index()` action handles the `/` Vweb often uses convention over configuration and adding a new action requires no routing rules either: -```v +```v oksyntax fn (mut app App) time() vweb.Result { app.vweb.text(time.now().format()) return vweb.Result{} @@ -132,7 +132,7 @@ Let's return an HTML view instead. Create `index.html` in the same directory: and update our `index()` action so that it returns the HTML view we just created: -```v +```v ignore pub fn (mut app App) index() vweb.Result { message := 'Hello, world from Vweb!' return $vweb.html() @@ -158,7 +158,8 @@ but V is a language with pure functions by default, and you won't be able to modify any data from a view. `@foo.bar()` will only work if the `bar()` method doesn't modify `foo`. -The HTML template is compiled to V during the compilation of the website, that's done by the `$vweb.html()` line. +The HTML template is compiled to V during the compilation of the website, +that's done by the `$vweb.html()` line. (`$` always means compile time actions in V.) offering the following benefits: - Great performance, since the templates don't need to be compiled @@ -203,7 +204,7 @@ Run the file with `sqlite3 blog.db < blog.sqlite`. Add a SQLite handle to `App`: -```v +```v oksyntax import sqlite struct App { @@ -217,7 +218,7 @@ pub mut: Modify the `init_once()` method we created earlier to connect to a database: -```v +```v oksyntax pub fn (mut app App) init_once() { db := sqlite.connect(':memory:') or { panic(err) } db.exec('create table `Article` (id integer primary key, title text default "", text text default "")') @@ -233,7 +234,7 @@ to have one DB connection for all requests. Create a new file `article.v`: -```v +```v oksyntax // article.v module main @@ -252,7 +253,7 @@ pub fn (app &App) find_all_articles() []Article { Let's fetch the articles in the `index()` action: -```v +```v ignore pub fn (app &App) index() vweb.Result { articles := app.find_all_articles() return $vweb.html() @@ -284,7 +285,7 @@ That was very simple, wasn't it? The built-in V ORM uses a syntax very similar to SQL. The queries are built with V. For example, if we only wanted to find articles with ids between 100 and 200, we'd do: -``` +```v oksyntax return sql app.db { select from Article where id >= 100 && id <= 200 } @@ -292,8 +293,7 @@ return sql app.db { Retrieving a single article is very simple: -```v - +```v oksyntax pub fn (app &App) retrieve_article() ?Article { return sql app.db { select from Article limit 1 @@ -304,7 +304,7 @@ pub fn (app &App) retrieve_article() ?Article { V ORM uses V's optionals for single values, which is very useful, since bad queries will always be handled by the developer: -```v +```v oksyntax article := app.retrieve_article(10) or { app.vweb.text('Article not found') return @@ -331,7 +331,7 @@ Create `new.html`: ``` -```v +```v oksyntax pub fn (mut app App) new_article() vweb.Result { title := app.vweb.form['title'] text := app.vweb.form['text'] @@ -369,7 +369,7 @@ This tutorial used the traditional server-side rendering. If you prefer to render everything on the client or need an API, creating JSON endpoints in V is very simple: -```v +```v oksyntax pub fn (mut app App) articles() vweb.Result { articles := app.find_all_articles() app.vweb.json(json.encode(articles)) diff --git a/vlib/encoding/csv/readme.md b/vlib/encoding/csv/README.md similarity index 100% rename from vlib/encoding/csv/readme.md rename to vlib/encoding/csv/README.md diff --git a/vlib/eventbus/README.md b/vlib/eventbus/README.md index 11625152af..bac5c06605 100644 --- a/vlib/eventbus/README.md +++ b/vlib/eventbus/README.md @@ -10,7 +10,8 @@ A module to provide eventing capabilities using pub/sub. **EventBus:** -1. `publish(name string, sender voidptr, args voidptr)` - publish an event with provided Params & name +1. `publish(name string, sender voidptr, args voidptr)` - publish an event with provided + Params & name 2. `clear_all()` - clear all subscribers 3. `has_subscriber(name string)` - check if a subscriber to an event exists @@ -18,7 +19,9 @@ A module to provide eventing capabilities using pub/sub. 1. `subscribe(name string, handler EventHandlerFn)` - subscribe to an event 2. `subscribe_once(name string, handler EventHandlerFn)` - subscribe only once to an event -3. `subscribe_method(name string, handler EventHandlerFn, receiver voidptr)` - subscribe to an event and also set the `receiver` as a parameter. Since it's not yet possible to send methods as parameters, this is a workaround. +3. `subscribe_method(name string, handler EventHandlerFn, receiver voidptr)` - subscribe to + an event and also set the `receiver` as a parameter. + Since it's not yet possible to send methods as parameters, this is a workaround. 4. `is_subscribed(name string)` - check if we are subscribed to an event 5. `unsubscribe(name string)` - unsubscribe from an event @@ -26,9 +29,8 @@ A module to provide eventing capabilities using pub/sub. The function given to `subscribe`, `subscribe_method` and `subscribe_once` must match this: -```v -fn(receiver voidptr, args voidptr, sender voidptr){ - +```v oksyntax +fn(receiver voidptr, args voidptr, sender voidptr) { } // Since V can map structs to voidptr, this also works @@ -52,7 +54,7 @@ _Note: As a general rule, you will need to **subscribe before publishing**._ **main.v** -```v +```v oksyntax module main import eventbus @@ -78,7 +80,7 @@ fn on_error(receiver voidptr, e &Error, work &Work) { **work.v** -```v +```v oksyntax module main struct Work{ @@ -100,12 +102,15 @@ fn do_work(){ ### Notes: -1. Each `EventBus` instance has it's own registry (i.e. there is no global event registry so you can't just subscribe to an event wherever you are. -2. Each `EventBus` has a `Subscriber` instance which will need to be either exposed or you can make small public helper functions specific to your module like (`onPress`, `onError`) and etc. -3. The `eventbus` module has some helpers to ease getting/setting of Params (since V doesn't support empty interfaces yet or reflection) so use them (see usage above). +1. Each `EventBus` instance has it's own registry (i.e. there is no global event registry + so you can't just subscribe to an event wherever you are. +2. Each `EventBus` has a `Subscriber` instance which will need to be either exposed or you can make + small public helper functions specific to your module like (`onPress`, `onError`) and etc. +3. The `eventbus` module has some helpers to ease getting/setting of Params + (since V doesn't support empty interfaces yet or reflection) so use them (see usage above). **The rationale behind separating Subscriber & Publisher:** -This is mainly for security because if publisher & subscriber are both passed around, -a client can easily publish events acting as the server. +This is mainly for security because if publisher & subscriber are both passed around, +a client can easily publish events acting as the server. So a client should only be able to use the Subscriber methods. diff --git a/vlib/net/html/README.md b/vlib/net/html/README.md index dcdef90f79..7cc8ea9548 100644 --- a/vlib/net/html/README.md +++ b/vlib/net/html/README.md @@ -1,86 +1,95 @@ # V HTML -A HTML parser made in V +A HTML parser made in V. ## Usage -If description below isn't enought, see test files +If the description below isn't enought, please look at the test files. ### Parser -Responsible for read HTML in full strings or splited string and returns all Tag objets of it HTML or return a DocumentObjectModel, that will try to find how the HTML Tree is. +Responsible for read HTML in full strings or splited string and returns all Tag objets of +it HTML or return a DocumentObjectModel, that will try to find how the HTML Tree is. #### split_parse(data string) -This functions is the main function called by parse method to fragment parse your HTML +This functions is the main function called by parse method to fragment parse your HTML. #### parse_html(data string, is_file bool) -This function is called passing a filename or a complete html data string to it +This function is called passing a filename or a complete html data string to it. #### add_code_tag(name string) -This function is used to add a tag for the parser ignore it's content. For example, if you have an html or XML with a custom tag, like `