Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore(docs): updated docs by adding shortcuts info #73

Merged
merged 3 commits into from
May 9, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 13 additions & 7 deletions docs/major-concepts/if.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,24 +9,31 @@ sidebar-position: 3
`ie` is a command line tool that computes [Manifest files](manifest-file.md).
It is the portal allowing users to interact with the Impact Framework.

The available options are:
The available options and their shortcuts are:

- `--manifest` or `-m`: path to an input manifest file
- `--output` or `-o` (optional): path to the output file where the results as saved
- `--stdout` or `-s` (optional): prints the output to stdout (console)
- `--override-params` or `-p` (optional): if you are an advanced user and you want to override our standard set of parameters and their definitions, you can provide the path to an alternative file as an argument to this command.
- `--help` or `-h`: prints out help instruction

- `--manifest`: path to an input manifest file
- `--output` (optional): path to the output file where the results as saved, if none is provided it prints to stdout.
- `--override-params` (optional): if you are an advanced user and you want to override our standard set of parameters and their definitions, you can provide the path to an alternative file as an argument to this command.

The only required command is `--manifest`. Without a valid path to a manifest file, `ie` has nothing to execute.

To use `ie`, you must first [write a manifest file](../users/how-to-write-manifests.md). Then, you can simply pass the path to the manifest file to `ie` on the command line.

```sh
ie --manifest /my-manifest.yml
ie --manifest /my-manifest.yml
## or using aliases
ie -m /my-manifest.yml
```

You can also pass a path where you would like to save the output file to. For example:

```sh
ie --manifest ./my-manifest.yml --output ./my-results.yml
## or using aliases
ie -m ./my-manifest.yml -o ./my-results.yml
```

> Note that you also need to add some config to your manifest file to enable exporting to a file. The config is as follows:
Expand All @@ -37,7 +44,6 @@ initialize:
```



If you omit the `--output` command, your results will be displayed in the console.
If you omit the `--output` command, your results won't be displayed in the console. You should use `--stdout` command for that.

For more information on the `ie` commands see the [CLI reference documentation](../reference/cli.md).
36 changes: 31 additions & 5 deletions docs/reference/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,22 +10,32 @@ If you have globally installed our `if` npm package, you can invoke the CLI usin

`ie <args>`

## `--manifest`
## `--manifest` , `-m`

The `--manifest` flag is the only required flag and tells `ie` where to find the manifest file that you want to execute. This command expects to receive the path where your manifest file is saved, as shown in the following example:

```sh
ie --manifest examples/manifests/my-manifest.yml
```

## `--output`
## `--output` , `-0`

The `--output` flag is optional and is used for defining a path to save your output data. If you provide the `--output` command with a path, your output data will be saved as a `.yml` file to disk. If you omit this command, your output data will be displayed in the terminal.
The `--output` flag is optional and is used for defining a path to save your output data. If you provide the `--output` command with a path, you also need to specify the file type in the `initialize.outputs` block in your manifest file. With both pieces of information, IF will save your output data to file.

Here is an example of `--output` being used to define a path:

```sh
ie --manifest examples/manifests/my-manifest.yml --output examples/outputs/my-outdata.yml
ie --manifest examples/manifests/my-manifest.yml --output examples/outputs/my-outdata
## or using aliases
ie -m examples/manifests/my-manifest.yml -o examples/outputs/my-outdata
```

If `my-manifest.yml` contains the following config, then a `yaml` file named `my-outdata.yml` will be created, containing the results from your IF run.

```yaml
initialize:
output:
- yaml
```
jmcook1186 marked this conversation as resolved.
Show resolved Hide resolved

### CSV export identifiers
Expand All @@ -35,10 +45,12 @@ If you want to save data to CSV, you have to select a specific metric to export.

```sh
ie --manifest demo.yml --output demo#carbon
## or
ie -m demo.yml -o demo#carbon
```


## `--override-params`
## `--override-params` , `-p`

The `override-params` command is used when you want to discard our recommended set of parameters and associated units and aggregation methods and instead provide your own. We do not recommend this, and if you use this feature you take full responsibility for any errors you introduce downstream, including unit or aggregation errors. This is why we hide the ability to override the parameters behind a CLI command - it is an advanced feature that you should only use if you really know what you are doing.

Expand All @@ -48,4 +60,18 @@ For example:

```sh
ie --manifest <your manifest> --override-params <path-to-your-params-file>
## or using aliases
ie -m <your manifest> -p <path-to-your-params-file>
```


## `--help` , `-h`

The `--help` command provides information about all available commands in order to help you easily find the command you need.

Example:
```sh
ie --help
## or using alias
ie -h
```