mirror
/
hurl
mirror of https://github.com/Orange-OpenSource/hurl
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update README for docs and add script for updating all docs.

This commit is contained in:
Jean-Christophe Amiel 2025-05-20 10:16:03 +02:00
parent 037b23ad4d
commit ef26155c33
No known key found for this signature in database
GPG Key ID: 07FF11CFD55356CC
7 changed files with 60 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
README.md
View File

@ -1352,7 +1352,7 @@ will follow a redirection only for the second entry.
| <a href="#location-trusted" id="location-trusted"><code>--location-trusted</code></a> | Like [`-L, --location`](#location), but allows sending the name + password to all hosts that the site may redirect to.<br>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).<br> | | <a href="#location-trusted" id="location-trusted"><code>--location-trusted</code></a> | Like [`-L, --location`](#location), but allows sending the name + password to all hosts that the site may redirect to.<br>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).<br> |
| <a href="#max-filesize" id="max-filesize"><code>--max-filesize &lt;BYTES&gt;</code></a> | 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.<br><br>This is a cli-only option.<br> | | <a href="#max-filesize" id="max-filesize"><code>--max-filesize &lt;BYTES&gt;</code></a> | 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.<br><br>This is a cli-only option.<br> |
| <a href="#max-redirs" id="max-redirs"><code>--max-redirs &lt;NUM&gt;</code></a> | Set maximum number of redirection-followings allowed<br><br>By default, the limit is set to 50 redirections. Set this option to -1 to make it unlimited.<br> | | <a href="#max-redirs" id="max-redirs"><code>--max-redirs &lt;NUM&gt;</code></a> | Set maximum number of redirection-followings allowed<br><br>By default, the limit is set to 50 redirections. Set this option to -1 to make it unlimited.<br> |
| <a href="#max-time" id="max-time"><code>-m, --max-time &lt;SECONDS&gt;</code></a> | Maximum time in seconds that you allow a request/response to take. This is the standard timeout.<br><br>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.<br><br>See also [`--connect-timeout`](#connect-timeout). | | <a href="#max-time" id="max-time"><code>-m, --max-time &lt;SECONDS&gt;</code></a> | Maximum time in seconds that you allow a request/response to take. This is the standard timeout.<br><br>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.<br><br>See also [`--connect-timeout`](#connect-timeout).<br><br>This is a cli-only option.<br> |
| <a href="#netrc" id="netrc"><code>-n, --netrc</code></a> | Scan the .netrc file in the user's home directory for the username and password.<br><br>See also [`--netrc-file`](#netrc-file) and [`--netrc-optional`](#netrc-optional).<br> | | <a href="#netrc" id="netrc"><code>-n, --netrc</code></a> | Scan the .netrc file in the user's home directory for the username and password.<br><br>See also [`--netrc-file`](#netrc-file) and [`--netrc-optional`](#netrc-optional).<br> |
| <a href="#netrc-file" id="netrc-file"><code>--netrc-file &lt;FILE&gt;</code></a> | Like [`--netrc`](#netrc), but provide the path to the netrc file.<br><br>See also [`--netrc-optional`](#netrc-optional).<br> | | <a href="#netrc-file" id="netrc-file"><code>--netrc-file &lt;FILE&gt;</code></a> | Like [`--netrc`](#netrc), but provide the path to the netrc file.<br><br>See also [`--netrc-optional`](#netrc-optional).<br> |
| <a href="#netrc-optional" id="netrc-optional"><code>--netrc-optional</code></a> | Similar to [`--netrc`](#netrc), but make the .netrc usage optional.<br><br>See also [`--netrc-file`](#netrc-file).<br> | | <a href="#netrc-optional" id="netrc-optional"><code>--netrc-optional</code></a> | Similar to [`--netrc`](#netrc), but make the .netrc usage optional.<br><br>See also [`--netrc-file`](#netrc-file).<br> |
@ -1362,6 +1362,7 @@ will follow a redirection only for the second entry.
| <a href="#output" id="output"><code>-o, --output &lt;FILE&gt;</code></a> | Write output to FILE instead of stdout.<br> | | <a href="#output" id="output"><code>-o, --output &lt;FILE&gt;</code></a> | Write output to FILE instead of stdout.<br> |
| <a href="#parallel" id="parallel"><code>--parallel</code></a> | Run files in parallel.<br><br>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.<br><br>See also [`--jobs`](#jobs).<br><br>This is a cli-only option.<br> | | <a href="#parallel" id="parallel"><code>--parallel</code></a> | Run files in parallel.<br><br>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.<br><br>See also [`--jobs`](#jobs).<br><br>This is a cli-only option.<br> |
| <a href="#path-as-is" id="path-as-is"><code>--path-as-is</code></a> | 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.<br> | | <a href="#path-as-is" id="path-as-is"><code>--path-as-is</code></a> | 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.<br> |
| <a href="#progress-bar" id="progress-bar"><code>--progress-bar</code></a> | 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.<br><br>This is a cli-only option.<br> |
| <a href="#proxy" id="proxy"><code>-x, --proxy &lt;[PROTOCOL://]HOST[:PORT]&gt;</code></a> | Use the specified proxy.<br> | | <a href="#proxy" id="proxy"><code>-x, --proxy &lt;[PROTOCOL://]HOST[:PORT]&gt;</code></a> | Use the specified proxy.<br> |
| <a href="#repeat" id="repeat"><code>--repeat &lt;NUM&gt;</code></a> | Repeat the input files sequence NUM times, -1 for infinite loop. Given a.hurl, b.hurl, c.hurl as input, repeat two<br>times will run a.hurl, b.hurl, c.hurl, a.hurl, b.hurl, c.hurl.<br><br>This is a cli-only option.<br> | | <a href="#repeat" id="repeat"><code>--repeat &lt;NUM&gt;</code></a> | Repeat the input files sequence NUM times, -1 for infinite loop. Given a.hurl, b.hurl, c.hurl as input, repeat two<br>times will run a.hurl, b.hurl, c.hurl, a.hurl, b.hurl, c.hurl.<br><br>This is a cli-only option.<br> |
| <a href="#report-html" id="report-html"><code>--report-html &lt;DIR&gt;</code></a> | Generate HTML report in DIR.<br><br>If the HTML report already exists, it will be updated with the new test results.<br><br>This is a cli-only option.<br> | | <a href="#report-html" id="report-html"><code>--report-html &lt;DIR&gt;</code></a> | Generate HTML report in DIR.<br><br>If the HTML report already exists, it will be updated with the new test results.<br><br>This is a cli-only option.<br> |
@ -1563,31 +1564,31 @@ Hurl depends on libssl, libcurl and libxml2 native libraries. You will need thei
#### Debian based distributions #### Debian based distributions
```shell ```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 #### Fedora based distributions
```shell ```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 #### Red Hat based distributions
```shell ```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 #### Arch based distributions
```shell ```shell
$ pacman -S --noconfirm pkgconf gcc glibc openssl libxml2 $ pacman -S --noconfirm pkgconf gcc glibc openssl libxml2 clang
``` ```
#### Alpine based distributions #### Alpine based distributions
```shell ```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 ### Build on macOS

12
bin/docs/update_all.sh Executable file
View File

@ -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

29
docs/README.md
View File

@ -3,7 +3,30 @@
This directory is the canonical source for Hurl documentation. The site <https://hurl.dev>, powered by Jekyll, This directory is the canonical source for Hurl documentation. The site <https://hurl.dev>, powered by Jekyll,
is generated from it. If you want to modify <https://hurl.dev>, you can make a PR in this repo. is generated from it. If you want to modify <https://hurl.dev>, 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 <https://crates.io> 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 <https://github.com/Orange-OpenSource/hurl/tree/master/docs/manual>. The canonical source for the Hurl manual pages is at <https://github.com/Orange-OpenSource/hurl/tree/master/docs/manual>.
The markdown files [`hurl.md`] and [`hurlfmt.md`] are used : 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 docs/manual/hurlfmt.md => docs/manual/hurlfmt.1
``` ```
## READMEs ### READMEs
[GitHub README] and [crates.io README] are generated from the canonical docs. [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 docs/*.md => packages/hurl/README.md
``` ```
## Scripts ### Scripts to update manual and READMEs
1. generate manual 1. generate manual
2. generate <hurl.dev> manual 2. generate <hurl.dev> manual

1
docs/manual.md
View File

@ -194,6 +194,7 @@ will follow a redirection only for the second entry.
| <a href="#output" id="output"><code>-o, --output &lt;FILE&gt;</code></a> | Write output to FILE instead of stdout.<br> | | <a href="#output" id="output"><code>-o, --output &lt;FILE&gt;</code></a> | Write output to FILE instead of stdout.<br> |
| <a href="#parallel" id="parallel"><code>--parallel</code></a> | Run files in parallel.<br><br>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.<br><br>See also [`--jobs`](#jobs).<br><br>This is a cli-only option.<br> | | <a href="#parallel" id="parallel"><code>--parallel</code></a> | Run files in parallel.<br><br>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.<br><br>See also [`--jobs`](#jobs).<br><br>This is a cli-only option.<br> |
| <a href="#path-as-is" id="path-as-is"><code>--path-as-is</code></a> | 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.<br> | | <a href="#path-as-is" id="path-as-is"><code>--path-as-is</code></a> | 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.<br> |
| <a href="#progress-bar" id="progress-bar"><code>--progress-bar</code></a> | 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.<br><br>This is a cli-only option.<br> |
| <a href="#proxy" id="proxy"><code>-x, --proxy &lt;[PROTOCOL://]HOST[:PORT]&gt;</code></a> | Use the specified proxy.<br> | | <a href="#proxy" id="proxy"><code>-x, --proxy &lt;[PROTOCOL://]HOST[:PORT]&gt;</code></a> | Use the specified proxy.<br> |
| <a href="#repeat" id="repeat"><code>--repeat &lt;NUM&gt;</code></a> | Repeat the input files sequence NUM times, -1 for infinite loop. Given a.hurl, b.hurl, c.hurl as input, repeat two<br>times will run a.hurl, b.hurl, c.hurl, a.hurl, b.hurl, c.hurl.<br><br>This is a cli-only option.<br> | | <a href="#repeat" id="repeat"><code>--repeat &lt;NUM&gt;</code></a> | Repeat the input files sequence NUM times, -1 for infinite loop. Given a.hurl, b.hurl, c.hurl as input, repeat two<br>times will run a.hurl, b.hurl, c.hurl, a.hurl, b.hurl, c.hurl.<br><br>This is a cli-only option.<br> |
| <a href="#report-html" id="report-html"><code>--report-html &lt;DIR&gt;</code></a> | Generate HTML report in DIR.<br><br>If the HTML report already exists, it will be updated with the new test results.<br><br>This is a cli-only option.<br> | | <a href="#report-html" id="report-html"><code>--report-html &lt;DIR&gt;</code></a> | Generate HTML report in DIR.<br><br>If the HTML report already exists, it will be updated with the new test results.<br><br>This is a cli-only option.<br> |

8
docs/manual/hurl.1
View File

@ -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 .SH NAME
hurl - run and test HTTP requests. 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. 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]> " .IP "-x, --proxy <[PROTOCOL://]HOST[:PORT]> "
Use the specified proxy. Use the specified proxy.

2
docs/manual/hurlfmt.1
View File

@ -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 .SH NAME
hurlfmt - format Hurl files hurlfmt - format Hurl files

11
packages/hurl/README.md
View File

@ -1362,6 +1362,7 @@ will follow a redirection only for the second entry.
| <a href="#output" id="output"><code>-o, --output &lt;FILE&gt;</code></a> | Write output to FILE instead of stdout.<br> | | <a href="#output" id="output"><code>-o, --output &lt;FILE&gt;</code></a> | Write output to FILE instead of stdout.<br> |
| <a href="#parallel" id="parallel"><code>--parallel</code></a> | Run files in parallel.<br><br>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.<br><br>See also [`--jobs`](#jobs).<br><br>This is a cli-only option.<br> | | <a href="#parallel" id="parallel"><code>--parallel</code></a> | Run files in parallel.<br><br>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.<br><br>See also [`--jobs`](#jobs).<br><br>This is a cli-only option.<br> |
| <a href="#path-as-is" id="path-as-is"><code>--path-as-is</code></a> | 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.<br> | | <a href="#path-as-is" id="path-as-is"><code>--path-as-is</code></a> | 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.<br> |
| <a href="#progress-bar" id="progress-bar"><code>--progress-bar</code></a> | 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.<br><br>This is a cli-only option.<br> |
| <a href="#proxy" id="proxy"><code>-x, --proxy &lt;[PROTOCOL://]HOST[:PORT]&gt;</code></a> | Use the specified proxy.<br> | | <a href="#proxy" id="proxy"><code>-x, --proxy &lt;[PROTOCOL://]HOST[:PORT]&gt;</code></a> | Use the specified proxy.<br> |
| <a href="#repeat" id="repeat"><code>--repeat &lt;NUM&gt;</code></a> | Repeat the input files sequence NUM times, -1 for infinite loop. Given a.hurl, b.hurl, c.hurl as input, repeat two<br>times will run a.hurl, b.hurl, c.hurl, a.hurl, b.hurl, c.hurl.<br><br>This is a cli-only option.<br> | | <a href="#repeat" id="repeat"><code>--repeat &lt;NUM&gt;</code></a> | Repeat the input files sequence NUM times, -1 for infinite loop. Given a.hurl, b.hurl, c.hurl as input, repeat two<br>times will run a.hurl, b.hurl, c.hurl, a.hurl, b.hurl, c.hurl.<br><br>This is a cli-only option.<br> |
| <a href="#report-html" id="report-html"><code>--report-html &lt;DIR&gt;</code></a> | Generate HTML report in DIR.<br><br>If the HTML report already exists, it will be updated with the new test results.<br><br>This is a cli-only option.<br> | | <a href="#report-html" id="report-html"><code>--report-html &lt;DIR&gt;</code></a> | Generate HTML report in DIR.<br><br>If the HTML report already exists, it will be updated with the new test results.<br><br>This is a cli-only option.<br> |
@ -1563,31 +1564,31 @@ Hurl depends on libssl, libcurl and libxml2 native libraries. You will need thei
#### Debian based distributions #### Debian based distributions
```shell ```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 #### Fedora based distributions
```shell ```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 #### Red Hat based distributions
```shell ```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 #### Arch based distributions
```shell ```shell
$ pacman -S --noconfirm pkgconf gcc glibc openssl libxml2 $ pacman -S --noconfirm pkgconf gcc glibc openssl libxml2 clang
``` ```
#### Alpine based distributions #### Alpine based distributions
```shell ```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 ### Build on macOS