hurl/docs

Hurl Documentation

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.

[!TIP] TLDR To update all docs:

$ 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 :

• to generate manual pages hurl.1 and hurlfmt.1
• to generate Markdown documentation page manual.md for https://hurl.dev

Dependencies:

docs/manual/hurl.md => docs/manual/hurl.1
docs/manual/hurl.md => docs/manual.md

docs/manual/hurlfmt.md => docs/manual/hurlfmt.1

READMEs

GitHub README and crates.io README are generated from the canonical docs.

Dependencies:

docs/*.md => README.md
docs/*.md => packages/hurl/README.md

Scripts to update manual and READMEs

1. generate manual
2. generate <hurl.dev> manual
3. generate GitHub README
4. generate crates.io README

$ cd ..
$ 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