diff --git a/README.md b/README.md index a3e8aa3250..f53fdf1107 100644 --- a/README.md +++ b/README.md @@ -1352,7 +1352,7 @@ will follow a redirection only for the second entry. | --location-trusted | Like [`-L, --location`](#location), but allows sending the name + password to all hosts that the site may redirect to.
This may or may not introduce a security breach if the site redirects you to a site to which you send your authentication info (which is plaintext in the case of HTTP Basic authentication).
| | --max-filesize <BYTES> | Specify the maximum size in bytes of a file to download. If the file requested is larger than this value, the transfer does not start.

This is a cli-only option.
| | --max-redirs <NUM> | Set maximum number of redirection-followings allowed

By default, the limit is set to 50 redirections. Set this option to -1 to make it unlimited.
| -| -m, --max-time <SECONDS> | Maximum time in seconds that you allow a request/response to take. This is the standard timeout.

You can specify time units in the maximum time expression. Set Hurl to use a maximum time of 20 seconds with `--max-time 20s` or set it to 35,000 milliseconds with `--max-time 35000ms`. No spaces allowed.

See also [`--connect-timeout`](#connect-timeout). | +| -m, --max-time <SECONDS> | Maximum time in seconds that you allow a request/response to take. This is the standard timeout.

You can specify time units in the maximum time expression. Set Hurl to use a maximum time of 20 seconds with `--max-time 20s` or set it to 35,000 milliseconds with `--max-time 35000ms`. No spaces allowed.

See also [`--connect-timeout`](#connect-timeout).

This is a cli-only option.
| | -n, --netrc | Scan the .netrc file in the user's home directory for the username and password.

See also [`--netrc-file`](#netrc-file) and [`--netrc-optional`](#netrc-optional).
| | --netrc-file <FILE> | Like [`--netrc`](#netrc), but provide the path to the netrc file.

See also [`--netrc-optional`](#netrc-optional).
| | --netrc-optional | Similar to [`--netrc`](#netrc), but make the .netrc usage optional.

See also [`--netrc-file`](#netrc-file).
| @@ -1362,6 +1362,7 @@ will follow a redirection only for the second entry. | -o, --output <FILE> | Write output to FILE instead of stdout.
| | --parallel | Run files in parallel.

Each Hurl file is executed in its own worker thread, without sharing anything with the other workers. The default run mode is sequential. Parallel execution is by default in [`--test`](#test) mode.

See also [`--jobs`](#jobs).

This is a cli-only option.
| | --path-as-is | Tell Hurl to not handle sequences of /../ or /./ in the given URL path. Normally Hurl will squash or merge them according to standards but with this option set you tell it not to do that.
| +| --progress-bar | Display a progress bar in test mode. The progress bar is displayed only in interactive TTYs. This option forces the progress bar to be displayed even in non-interactive TTYs.

This is a cli-only option.
| | -x, --proxy <[PROTOCOL://]HOST[:PORT]> | Use the specified proxy.
| | --repeat <NUM> | Repeat the input files sequence NUM times, -1 for infinite loop. Given a.hurl, b.hurl, c.hurl as input, repeat two
times will run a.hurl, b.hurl, c.hurl, a.hurl, b.hurl, c.hurl.

This is a cli-only option.
| | --report-html <DIR> | Generate HTML report in DIR.

If the HTML report already exists, it will be updated with the new test results.

This is a cli-only option.
| @@ -1563,31 +1564,31 @@ Hurl depends on libssl, libcurl and libxml2 native libraries. You will need thei #### Debian based distributions ```shell -$ apt install -y build-essential pkg-config libssl-dev libcurl4-openssl-dev libxml2-dev +$ apt install -y build-essential pkg-config libssl-dev libcurl4-openssl-dev libxml2-dev libclang-dev ``` #### Fedora based distributions ```shell -$ dnf install -y pkgconf-pkg-config gcc openssl-devel libxml2-devel +$ dnf install -y pkgconf-pkg-config gcc openssl-devel libxml2-devel clang-devel ``` #### Red Hat based distributions ```shell -$ yum install -y pkg-config gcc openssl-devel libxml2-devel +$ yum install -y pkg-config gcc openssl-devel libxml2-devel clang-devel ``` #### Arch based distributions ```shell -$ pacman -S --noconfirm pkgconf gcc glibc openssl libxml2 +$ pacman -S --noconfirm pkgconf gcc glibc openssl libxml2 clang ``` #### Alpine based distributions ```shell -$ apk add curl-dev gcc libxml2-dev musl-dev openssl-dev +$ apk add curl-dev gcc libxml2-dev musl-dev openssl-dev clang-dev ``` ### Build on macOS diff --git a/bin/docs/update_all.sh b/bin/docs/update_all.sh new file mode 100755 index 0000000000..eb9279148e --- /dev/null +++ b/bin/docs/update_all.sh @@ -0,0 +1,12 @@ +#!/bin/bash +set -Eeuo pipefail + +# First generates Rust code, bash completion, part of hurl.md and hurlfmt.md +python3 bin/spec/options/generate_all.py + +# Regenerates manual, READMEs etc.. +python3 bin/release/gen_manpage.py docs/manual/hurl.md > docs/manual/hurl.1 +python3 bin/release/gen_manpage.py docs/manual/hurlfmt.md > docs/manual/hurlfmt.1 +python3 bin/docs/build_man_md.py docs/manual/hurl.md > docs/manual.md +python3 bin/docs/build_readme.py github > README.md +python3 bin/docs/build_readme.py crates > packages/hurl/README.md diff --git a/docs/README.md b/docs/README.md index 2c32975b22..700440bff2 100644 --- a/docs/README.md +++ b/docs/README.md @@ -3,7 +3,30 @@ This directory is the canonical source for Hurl documentation. The site , powered by Jekyll, is generated from it. If you want to modify , you can make a PR in this repo. -## Manual Page +> [!TIP] +> TLDR +> To update all docs: +> ```shell +> $ bin/docs/update_all.sh +> ``` + +## Documentation Generation + +Some files are dependent and needs to be generated appropriated. +- `docs/spec/options/**/*.option`: define the command line option of `hurl` and `hurlfmt`. These are text declarative +files that will update project files (Rust files to produce the output of `--help`, Rust file options etc..., shell completion +script etc...). These files are also used to generate part of man files `docs/manual/hurl.md`, `docs/manual/hurlfmt.md` +- `docs/manual/hurl.md`/`docs/manual/hurlfmt.md`: Markdown source files of man pages `hurl.1``hurlfmt.1` +- `README.md` / `packages/hurl/README.md`, / `packages/hurlfmt/README.md`: GitHub and READMEs. These +files are entirely generated from previous files (`.options` files, `.md` manual) + + +### Options + +Hurl options files describes each option of `hurl` and `hurlfmt`. They're used to generated various files of the project. + + +### Manual Page The canonical source for the Hurl manual pages is at . The markdown files [`hurl.md`] and [`hurlfmt.md`] are used : @@ -20,7 +43,7 @@ docs/manual/hurl.md => docs/manual.md docs/manual/hurlfmt.md => docs/manual/hurlfmt.1 ``` -## READMEs +### READMEs [GitHub README] and [crates.io README] are generated from the canonical docs. @@ -31,7 +54,7 @@ docs/*.md => README.md docs/*.md => packages/hurl/README.md ``` -## Scripts +### Scripts to update manual and READMEs 1. generate manual 2. generate manual diff --git a/docs/manual.md b/docs/manual.md index f7091c9c03..94b7bf391e 100644 --- a/docs/manual.md +++ b/docs/manual.md @@ -194,6 +194,7 @@ will follow a redirection only for the second entry. | -o, --output <FILE> | Write output to FILE instead of stdout.
| | --parallel | Run files in parallel.

Each Hurl file is executed in its own worker thread, without sharing anything with the other workers. The default run mode is sequential. Parallel execution is by default in [`--test`](#test) mode.

See also [`--jobs`](#jobs).

This is a cli-only option.
| | --path-as-is | Tell Hurl to not handle sequences of /../ or /./ in the given URL path. Normally Hurl will squash or merge them according to standards but with this option set you tell it not to do that.
| +| --progress-bar | Display a progress bar in test mode. The progress bar is displayed only in interactive TTYs. This option forces the progress bar to be displayed even in non-interactive TTYs.

This is a cli-only option.
| | -x, --proxy <[PROTOCOL://]HOST[:PORT]> | Use the specified proxy.
| | --repeat <NUM> | Repeat the input files sequence NUM times, -1 for infinite loop. Given a.hurl, b.hurl, c.hurl as input, repeat two
times will run a.hurl, b.hurl, c.hurl, a.hurl, b.hurl, c.hurl.

This is a cli-only option.
| | --report-html <DIR> | Generate HTML report in DIR.

If the HTML report already exists, it will be updated with the new test results.

This is a cli-only option.
| diff --git a/docs/manual/hurl.1 b/docs/manual/hurl.1 index 52c809026b..4b632f51d8 100644 --- a/docs/manual/hurl.1 +++ b/docs/manual/hurl.1 @@ -1,4 +1,4 @@ -.TH hurl 1 "24 Apr 2025" "hurl 7.0.0-SNAPSHOT" " Hurl Manual" +.TH hurl 1 "20 May 2025" "hurl 7.0.0-SNAPSHOT" " Hurl Manual" .SH NAME hurl - run and test HTTP requests. @@ -402,6 +402,12 @@ This is a cli-only option. Tell Hurl to not handle sequences of /../ or /./ in the given URL path. Normally Hurl will squash or merge them according to standards but with this option set you tell it not to do that. +.IP "--progress-bar " + +Display a progress bar in test mode. The progress bar is displayed only in interactive TTYs. This option forces the progress bar to be displayed even in non-interactive TTYs. + +This is a cli-only option. + .IP "-x, --proxy <[PROTOCOL://]HOST[:PORT]> " Use the specified proxy. diff --git a/docs/manual/hurlfmt.1 b/docs/manual/hurlfmt.1 index 6bda20c3ed..564dfd5366 100644 --- a/docs/manual/hurlfmt.1 +++ b/docs/manual/hurlfmt.1 @@ -1,4 +1,4 @@ -.TH hurl 1 "24 Apr 2025" "hurl 7.0.0-SNAPSHOT" " Hurl Manual" +.TH hurl 1 "20 May 2025" "hurl 7.0.0-SNAPSHOT" " Hurl Manual" .SH NAME hurlfmt - format Hurl files diff --git a/packages/hurl/README.md b/packages/hurl/README.md index ba10f23170..a50f9e81fc 100644 --- a/packages/hurl/README.md +++ b/packages/hurl/README.md @@ -1362,6 +1362,7 @@ will follow a redirection only for the second entry. | -o, --output <FILE> | Write output to FILE instead of stdout.
| | --parallel | Run files in parallel.

Each Hurl file is executed in its own worker thread, without sharing anything with the other workers. The default run mode is sequential. Parallel execution is by default in [`--test`](#test) mode.

See also [`--jobs`](#jobs).

This is a cli-only option.
| | --path-as-is | Tell Hurl to not handle sequences of /../ or /./ in the given URL path. Normally Hurl will squash or merge them according to standards but with this option set you tell it not to do that.
| +| --progress-bar | Display a progress bar in test mode. The progress bar is displayed only in interactive TTYs. This option forces the progress bar to be displayed even in non-interactive TTYs.

This is a cli-only option.
| | -x, --proxy <[PROTOCOL://]HOST[:PORT]> | Use the specified proxy.
| | --repeat <NUM> | Repeat the input files sequence NUM times, -1 for infinite loop. Given a.hurl, b.hurl, c.hurl as input, repeat two
times will run a.hurl, b.hurl, c.hurl, a.hurl, b.hurl, c.hurl.

This is a cli-only option.
| | --report-html <DIR> | Generate HTML report in DIR.

If the HTML report already exists, it will be updated with the new test results.

This is a cli-only option.
| @@ -1563,31 +1564,31 @@ Hurl depends on libssl, libcurl and libxml2 native libraries. You will need thei #### Debian based distributions ```shell -$ apt install -y build-essential pkg-config libssl-dev libcurl4-openssl-dev libxml2-dev +$ apt install -y build-essential pkg-config libssl-dev libcurl4-openssl-dev libxml2-dev libclang-dev ``` #### Fedora based distributions ```shell -$ dnf install -y pkgconf-pkg-config gcc openssl-devel libxml2-devel +$ dnf install -y pkgconf-pkg-config gcc openssl-devel libxml2-devel clang-devel ``` #### Red Hat based distributions ```shell -$ yum install -y pkg-config gcc openssl-devel libxml2-devel +$ yum install -y pkg-config gcc openssl-devel libxml2-devel clang-devel ``` #### Arch based distributions ```shell -$ pacman -S --noconfirm pkgconf gcc glibc openssl libxml2 +$ pacman -S --noconfirm pkgconf gcc glibc openssl libxml2 clang ``` #### Alpine based distributions ```shell -$ apk add curl-dev gcc libxml2-dev musl-dev openssl-dev +$ apk add curl-dev gcc libxml2-dev musl-dev openssl-dev clang-dev ``` ### Build on macOS