Orange-OpenSource/hurl
1
1
Fork 0
mirror of https://github.com/Orange-OpenSource/hurl.git synced 2024-09-11 05:35:53 +03:00
Code Issues Packages Projects Releases Wiki Activity

Update man and document documentation generation.

Browse Source
This commit is contained in:
jcamiel 2022-08-16 14:17:44 +02:00
parent 08fc128a9b
commit c0a8bbb544
No known key found for this signature in database
GPG Key ID: 07FF11CFD55356CC
9 changed files with 66 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
README.md
View File

@ -752,18 +752,19 @@ Option | Description
<a href="#no-output" id="no-output"><code>--no-output</code></a> | Suppress output. By default, Hurl outputs the body of the last response.<br/>
<a href="#noproxy" id="noproxy"><code>--noproxy &lt;no-proxy-list&gt;</code></a> | Comma-separated list of hosts which do not use a proxy.<br/>Override value from Environment variable no_proxy.<br/>
<a href="#output" id="output"><code>-o, --output &lt;file&gt;</code></a> | Write output to <file> instead of stdout.<br/>
<a href="#progress" id="progress"><code>--progress</code></a> | Print filename and status for each test (on stderr)<br/>
<a href="#progress" id="progress"><code>--progress</code></a> | Print filename and status for each test (on stderr)<br/><br/>Deprecated, use [`--test`](#test) or [`--json`](#json) instead.<br/>
<a href="#proxy" id="proxy"><code>-x, --proxy [protocol://]host[:port]</code></a> | Use the specified proxy.<br/>
<a href="#report-junit" id="report-junit"><code>--report-junit &lt;file&gt;</code></a> | Generate JUNIT <file>.<br/><br/>If the <file> report already exists, it will be updated with the new test results.<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/>
<a href="#summary" id="summary"><code>--summary</code></a> | Print test metrics at the end of the run (on stderr)<br/>
<a href="#test" id="test"><code>--test</code></a> | Activate test mode; equals [`--no-output`](#no-output) [`--progress`](#progress) [`--summary`](#summary)<br/>
<a href="#summary" id="summary"><code>--summary</code></a> | Print test metrics at the end of the run (on stderr)<br/><br/>Deprecated, use [`--test`](#test) or [`--json`](#json) instead.<br/>
<a href="#test" id="test"><code>--test</code></a> | Activate test mode: the HTTP response is not outputted anymore, progress is reported for each Hurl file tested and a text summary is displayed when all files have been run. <br/>
<a href="#to-entry" id="to-entry"><code>--to-entry &lt;entry-number&gt;</code></a> | Execute Hurl file to ENTRY_NUMBER (starting at 1).<br/>Ignore the remaining of the file. It is useful for debugging a session.<br/>
<a href="#user" id="user"><code>-u, --user &lt;user:password&gt;</code></a> | Add basic Authentication header to each request.<br/>
<a href="#user-agent" id="user-agent"><code>-A, --user-agent &lt;name&gt;</code></a> | Specify the User-Agent string to send to the HTTP server.<br/>
<a href="#variable" id="variable"><code>--variable &lt;name=value&gt;</code></a> | Define variable (name/value) to be used in Hurl templates.<br/>
<a href="#variables-file" id="variables-file"><code>--variables-file &lt;file&gt;</code></a> | Set properties file in which your define your variables.<br/><br/>Each variable is defined as name=value exactly as with [`--variable`](#variable) option.<br/><br/>Note that defining a variable twice produces an error.<br/>
<a href="#verbose" id="verbose"><code>-v, --verbose</code></a> | Turn on verbose output on standard error stream<br/>Useful for debugging.<br/><br/>A line starting with '>' means data sent by Hurl.<br/>A line staring with '<' means data received by Hurl.<br/>A line starting with '*' means additional info provided by Hurl.<br/><br/>If you only want HTTP headers in the output, -i, --include might be the option you're looking for.<br/>
<a href="#verbose" id="verbose"><code>-v, --verbose</code></a> | Turn on verbose output on standard error stream.<br/>Useful for debugging.<br/><br/>A line starting with '>' means data sent by Hurl.<br/>A line staring with '<' means data received by Hurl.<br/>A line starting with '*' means additional info provided by Hurl.<br/><br/>If you only want HTTP headers in the output, -i, --include might be the option you're looking for.<br/>
<a href="#very-verbose" id="very-verbose"><code>--very-verbose</code></a> | Turn on more verbose output on standard error stream.<br/><br/>In contrast to [`--verbose`](#verbose) option, this option outputs the full HTTP body request and<br/>response on standard error.<br/>
<a href="#help" id="help"><code>-h, --help</code></a> | Usage help. This lists all current command line options with a short description.<br/>
<a href="#version" id="version"><code>-V, --version</code></a> | Prints version information<br/>

2
bin/docs/build_man_md.py
View File

@ -6,7 +6,7 @@ This script converts Hurl man file to Markdown suitable for the Hurl canonical d
This tool takes the Hurl man file as a first argument.
Examples:
$ python3 build_man_md.py ../../docs/man/hurl.md > ../../docs/man-page.md
$ python3 bin/docs/build_man_md.py docs/man/hurl.md > docs/man-page.md
"""
import re

14
bin/docs/build_readme.py
View File

@ -4,8 +4,8 @@
This script uses Hurl doc to generate README suitable for GitHub and crates.io
Examples:
$ python3 build_readme.py github > ../../README.md
$ python3 build_readme.py crates > ../../packages/hurl/README.md
$ python3 bin/docs/build_readme.py github > README.md
$ python3 bin/docs/build_readme.py crates > packages/hurl/README.md
"""
import os
@ -55,7 +55,7 @@ def main(dest: str) -> int:
header_md = parse_markdown(text=header)
home = Path("../../docs/home.md").read_text()
home = Path("docs/home.md").read_text()
# We adapt the "Why Hurl" part to transform h2 tag back to markdown
def showcase_rep(m):
@ -74,12 +74,10 @@ def main(dest: str) -> int:
]
home_md.remove_nodes(logo_nodes)
samples_md = parse_markdown(text=Path("../../docs/samples.md").read_text())
usage_md = parse_markdown(text=Path("../../docs/man-page.md").read_text())
samples_md = parse_markdown(text=Path("docs/samples.md").read_text())
usage_md = parse_markdown(text=Path("docs/man-page.md").read_text())
installation_md = parse_markdown(
text=Path("../../docs/installation.md").read_text()
)
installation_md = parse_markdown(text=Path("docs/installation.md").read_text())
body_md = MarkdownDoc()
body_md.extend(samples_md)

15
docs/README.md
View File

@ -28,6 +28,21 @@ docs/*.md => README.md
docs/*.md => packages/hurl/README.md
```
## Scripts
1. generate man pages
2. generate <hurl.dev> man page
3. generate GitHub README
4. generate crates.io README
```bash
$ python3 bin/release/gen_manpage.py docs/man/hurl.md > docs/man/hurl.1
$ python3 bin/release/gen_manpage.py docs/man/hurlfmt.md > docs/man/hurlfmt.1
$ python3 bin/docs/build_man_md.py docs/man/hurl.md > docs/man-page.md
$ python3 bin/docs/build_readme.py github > README.md
$ python3 bin/docs/build_readme.py crates > packages/hurl/README.md
```
[`hurl.md`]: https://github.com/Orange-OpenSource/hurl/tree/master/docs/man/hurl.md
[`hurlfmt.md`]: https://github.com/Orange-OpenSource/hurl/tree/master/docs/man/hurlfmt.md

9
docs/man-page.md
View File

@ -168,18 +168,19 @@ Option | Description
<a href="#no-output" id="no-output"><code>--no-output</code></a> | Suppress output. By default, Hurl outputs the body of the last response.<br/>
<a href="#noproxy" id="noproxy"><code>--noproxy &lt;no-proxy-list&gt;</code></a> | Comma-separated list of hosts which do not use a proxy.<br/>Override value from Environment variable no_proxy.<br/>
<a href="#output" id="output"><code>-o, --output &lt;file&gt;</code></a> | Write output to <file> instead of stdout.<br/>
<a href="#progress" id="progress"><code>--progress</code></a> | Print filename and status for each test (on stderr)<br/>
<a href="#progress" id="progress"><code>--progress</code></a> | Print filename and status for each test (on stderr)<br/><br/>Deprecated, use [`--test`](#test) or [`--json`](#json) instead.<br/>
<a href="#proxy" id="proxy"><code>-x, --proxy [protocol://]host[:port]</code></a> | Use the specified proxy.<br/>
<a href="#report-junit" id="report-junit"><code>--report-junit &lt;file&gt;</code></a> | Generate JUNIT <file>.<br/><br/>If the <file> report already exists, it will be updated with the new test results.<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/>
<a href="#summary" id="summary"><code>--summary</code></a> | Print test metrics at the end of the run (on stderr)<br/>
<a href="#test" id="test"><code>--test</code></a> | Activate test mode; equals [`--no-output`](#no-output) [`--progress`](#progress) [`--summary`](#summary)<br/>
<a href="#summary" id="summary"><code>--summary</code></a> | Print test metrics at the end of the run (on stderr)<br/><br/>Deprecated, use [`--test`](#test) or [`--json`](#json) instead.<br/>
<a href="#test" id="test"><code>--test</code></a> | Activate test mode: the HTTP response is not outputted anymore, progress is reported for each Hurl file tested and a text summary is displayed when all files have been run. <br/>
<a href="#to-entry" id="to-entry"><code>--to-entry &lt;entry-number&gt;</code></a> | Execute Hurl file to ENTRY_NUMBER (starting at 1).<br/>Ignore the remaining of the file. It is useful for debugging a session.<br/>
<a href="#user" id="user"><code>-u, --user &lt;user:password&gt;</code></a> | Add basic Authentication header to each request.<br/>
<a href="#user-agent" id="user-agent"><code>-A, --user-agent &lt;name&gt;</code></a> | Specify the User-Agent string to send to the HTTP server.<br/>
<a href="#variable" id="variable"><code>--variable &lt;name=value&gt;</code></a> | Define variable (name/value) to be used in Hurl templates.<br/>
<a href="#variables-file" id="variables-file"><code>--variables-file &lt;file&gt;</code></a> | Set properties file in which your define your variables.<br/><br/>Each variable is defined as name=value exactly as with [`--variable`](#variable) option.<br/><br/>Note that defining a variable twice produces an error.<br/>
<a href="#verbose" id="verbose"><code>-v, --verbose</code></a> | Turn on verbose output on standard error stream<br/>Useful for debugging.<br/><br/>A line starting with '>' means data sent by Hurl.<br/>A line staring with '<' means data received by Hurl.<br/>A line starting with '*' means additional info provided by Hurl.<br/><br/>If you only want HTTP headers in the output, -i, --include might be the option you're looking for.<br/>
<a href="#verbose" id="verbose"><code>-v, --verbose</code></a> | Turn on verbose output on standard error stream.<br/>Useful for debugging.<br/><br/>A line starting with '>' means data sent by Hurl.<br/>A line staring with '<' means data received by Hurl.<br/>A line starting with '*' means additional info provided by Hurl.<br/><br/>If you only want HTTP headers in the output, -i, --include might be the option you're looking for.<br/>
<a href="#very-verbose" id="very-verbose"><code>--very-verbose</code></a> | Turn on more verbose output on standard error stream.<br/><br/>In contrast to [`--verbose`](#verbose) option, this option outputs the full HTTP body request and<br/>response on standard error.<br/>
<a href="#help" id="help"><code>-h, --help</code></a> | Usage help. This lists all current command line options with a short description.<br/>
<a href="#version" id="version"><code>-V, --version</code></a> | Prints version information<br/>

16
docs/man/hurl.1
View File

@ -236,6 +236,8 @@ Write output to <file> instead of stdout.
Print filename and status for each test (on stderr)
Deprecated, use \fI--test\fP or \fI--json\fP instead.
.IP "-x, --proxy [protocol://]host[:port] "
Use the specified proxy.
@ -256,9 +258,11 @@ If the HTML report already exists, it will be updated with the new test results.
Print test metrics at the end of the run (on stderr)
Deprecated, use \fI--test\fP or \fI--json\fP instead.
.IP "--test "
Activate test mode; equals \fI--no-output\fP \fI--progress\fP \fI--summary\fP
Activate test mode: the HTTP response is not outputted anymore, progress is reported for each Hurl file tested and a text summary is displayed when all files have been run.
.IP "--to-entry <entry-number> "
@ -287,7 +291,7 @@ Note that defining a variable twice produces an error.
.IP "-v, --verbose "
Turn on verbose output on standard error stream
Turn on verbose output on standard error stream.
Useful for debugging.
A line starting with '>' means data sent by Hurl.
@ -296,6 +300,14 @@ A line starting with '*' means additional info provided by Hurl.
If you only want HTTP headers in the output, -i, --include might be the option you're looking for.
.IP "--very-verbose "
Turn on more verbose output on standard error stream.
In contrast to \fI--verbose\fP option, this option outputs the full HTTP body request and
response on standard error.
.IP "-h, --help "
Usage help. This lists all current command line options with a short description.

16
docs/man/hurl.md
View File

@ -255,6 +255,8 @@ Write output to <file> instead of stdout.
Print filename and status for each test (on stderr)
Deprecated, use [`--test`](#test) or [`--json`](#json) instead.
### -x, --proxy [protocol://]host[:port] {#proxy}
Use the specified proxy.
@ -275,9 +277,11 @@ If the HTML report already exists, it will be updated with the new test results.
Print test metrics at the end of the run (on stderr)
Deprecated, use [`--test`](#test) or [`--json`](#json) instead.
### --test {#test}
Activate test mode; equals [`--no-output`](#no-output) [`--progress`](#progress) [`--summary`](#summary)
Activate test mode: the HTTP response is not outputted anymore, progress is reported for each Hurl file tested and a text summary is displayed when all files have been run.
### --to-entry <entry-number> {#to-entry}
@ -306,7 +310,7 @@ Note that defining a variable twice produces an error.
### -v, --verbose {#verbose}
Turn on verbose output on standard error stream
Turn on verbose output on standard error stream.
Useful for debugging.
A line starting with '>' means data sent by Hurl.
@ -315,6 +319,14 @@ A line starting with '*' means additional info provided by Hurl.
If you only want HTTP headers in the output, -i, --include might be the option you're looking for.
### --very-verbose {#very-verbose}
Turn on more verbose output on standard error stream.
In contrast to [`--verbose`](#verbose) option, this option outputs the full HTTP body request and
response on standard error.
### -h, --help {#help}
Usage help. This lists all current command line options with a short description.

2
docs/man/hurlfmt.1
View File

@ -1,4 +1,4 @@
.TH hurl 1 "23 Jun 2022" "hurl 1.7.0-snapshot" " Hurl Manual"
.TH hurl 1 "16 Aug 2022" "hurl 1.7.0-snapshot" " Hurl Manual"
.SH NAME
hurlfmt - format Hurl files

9
packages/hurl/README.md
View File

@ -752,18 +752,19 @@ Option | Description
<a href="#no-output" id="no-output"><code>--no-output</code></a> | Suppress output. By default, Hurl outputs the body of the last response.<br/>
<a href="#noproxy" id="noproxy"><code>--noproxy &lt;no-proxy-list&gt;</code></a> | Comma-separated list of hosts which do not use a proxy.<br/>Override value from Environment variable no_proxy.<br/>
<a href="#output" id="output"><code>-o, --output &lt;file&gt;</code></a> | Write output to <file> instead of stdout.<br/>
<a href="#progress" id="progress"><code>--progress</code></a> | Print filename and status for each test (on stderr)<br/>
<a href="#progress" id="progress"><code>--progress</code></a> | Print filename and status for each test (on stderr)<br/><br/>Deprecated, use [`--test`](#test) or [`--json`](#json) instead.<br/>
<a href="#proxy" id="proxy"><code>-x, --proxy [protocol://]host[:port]</code></a> | Use the specified proxy.<br/>
<a href="#report-junit" id="report-junit"><code>--report-junit &lt;file&gt;</code></a> | Generate JUNIT <file>.<br/><br/>If the <file> report already exists, it will be updated with the new test results.<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/>
<a href="#summary" id="summary"><code>--summary</code></a> | Print test metrics at the end of the run (on stderr)<br/>
<a href="#test" id="test"><code>--test</code></a> | Activate test mode; equals [`--no-output`](#no-output) [`--progress`](#progress) [`--summary`](#summary)<br/>
<a href="#summary" id="summary"><code>--summary</code></a> | Print test metrics at the end of the run (on stderr)<br/><br/>Deprecated, use [`--test`](#test) or [`--json`](#json) instead.<br/>
<a href="#test" id="test"><code>--test</code></a> | Activate test mode: the HTTP response is not outputted anymore, progress is reported for each Hurl file tested and a text summary is displayed when all files have been run. <br/>
<a href="#to-entry" id="to-entry"><code>--to-entry &lt;entry-number&gt;</code></a> | Execute Hurl file to ENTRY_NUMBER (starting at 1).<br/>Ignore the remaining of the file. It is useful for debugging a session.<br/>
<a href="#user" id="user"><code>-u, --user &lt;user:password&gt;</code></a> | Add basic Authentication header to each request.<br/>
<a href="#user-agent" id="user-agent"><code>-A, --user-agent &lt;name&gt;</code></a> | Specify the User-Agent string to send to the HTTP server.<br/>
<a href="#variable" id="variable"><code>--variable &lt;name=value&gt;</code></a> | Define variable (name/value) to be used in Hurl templates.<br/>
<a href="#variables-file" id="variables-file"><code>--variables-file &lt;file&gt;</code></a> | Set properties file in which your define your variables.<br/><br/>Each variable is defined as name=value exactly as with [`--variable`](#variable) option.<br/><br/>Note that defining a variable twice produces an error.<br/>
<a href="#verbose" id="verbose"><code>-v, --verbose</code></a> | Turn on verbose output on standard error stream<br/>Useful for debugging.<br/><br/>A line starting with '>' means data sent by Hurl.<br/>A line staring with '<' means data received by Hurl.<br/>A line starting with '*' means additional info provided by Hurl.<br/><br/>If you only want HTTP headers in the output, -i, --include might be the option you're looking for.<br/>
<a href="#verbose" id="verbose"><code>-v, --verbose</code></a> | Turn on verbose output on standard error stream.<br/>Useful for debugging.<br/><br/>A line starting with '>' means data sent by Hurl.<br/>A line staring with '<' means data received by Hurl.<br/>A line starting with '*' means additional info provided by Hurl.<br/><br/>If you only want HTTP headers in the output, -i, --include might be the option you're looking for.<br/>
<a href="#very-verbose" id="very-verbose"><code>--very-verbose</code></a> | Turn on more verbose output on standard error stream.<br/><br/>In contrast to [`--verbose`](#verbose) option, this option outputs the full HTTP body request and<br/>response on standard error.<br/>
<a href="#help" id="help"><code>-h, --help</code></a> | Usage help. This lists all current command line options with a short description.<br/>
<a href="#version" id="version"><code>-V, --version</code></a> | Prints version information<br/>