Update README for docs and add script for updating all docs.
This commit is contained in:
Jean-Christophe Amiel
parent
037b23ad4d
commit
ef26155c33
13
README.md
13
README.md
|
|
@ -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="#max-filesize" id="max-filesize"><code>--max-filesize <BYTES></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 <NUM></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 <SECONDS></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 <SECONDS></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-file" id="netrc-file"><code>--netrc-file <FILE></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> |
|
||||
|
|
@ -1362,6 +1362,7 @@ will follow a redirection only for the second entry.
|
|||
| <a href="#output" id="output"><code>-o, --output <FILE></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="#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 <[PROTOCOL://]HOST[:PORT]></code></a> | Use the specified proxy.<br> |
|
||||
| <a href="#repeat" id="repeat"><code>--repeat <NUM></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 <DIR></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
|
||||
|
||||
```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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
@ -3,7 +3,30 @@
|
|||
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.
|
||||
|
||||
## 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 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 <hurl.dev> manual
|
||||
|
|
|
|||
|
|
@ -194,6 +194,7 @@ will follow a redirection only for the second entry.
|
|||
| <a href="#output" id="output"><code>-o, --output <FILE></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="#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 <[PROTOCOL://]HOST[:PORT]></code></a> | Use the specified proxy.<br> |
|
||||
| <a href="#repeat" id="repeat"><code>--repeat <NUM></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 <DIR></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> |
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -1362,6 +1362,7 @@ will follow a redirection only for the second entry.
|
|||
| <a href="#output" id="output"><code>-o, --output <FILE></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="#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 <[PROTOCOL://]HOST[:PORT]></code></a> | Use the specified proxy.<br> |
|
||||
| <a href="#repeat" id="repeat"><code>--repeat <NUM></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 <DIR></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
|
||||
|
||||
```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
|
||||
|
|
|
|||
Loading…
Reference in New Issue