README.md 4.44 KB
Newer Older
1 2
# `webis` Command

Michael Völske's avatar
Michael Völske committed
3 4 5 6 7 8
---

## [Installation Instructions](https://git.webis.de/code-generic/code-webis-cmd/wikis/webis-cmd-installation)

---

9
## Authors
10 11 12 13
* Janek Bevendorff
* Steve Goering
* Martin Potthast
* Michael Völske
14
* Johannes Kiesel
15 16

## About
Johannes Kiesel's avatar
Johannes Kiesel committed
17
The webis command is a helper utility for automating every-day tasks in our group.
18 19 20 21 22

## Requirements
* `python3`
* `pep8`

Johannes Kiesel's avatar
Johannes Kiesel committed
23
## Using `webis`
24
For usage help run:
25 26 27 28 29

```
./webis.py -h
```

Johannes Kiesel's avatar
Johannes Kiesel committed
30
Or look at the [cheatsheet](cheatsheet.txt)
31

Johannes Kiesel's avatar
Johannes Kiesel committed
32
### Install
Johannes Kiesel's avatar
Johannes Kiesel committed
33 34 35
If you are on a webis machine, `webis` should already be installed. If not, contact our administrators.

If you want to add the webis command to the PATH in your own machine (so that you don't have to specify it's full path every time, but can just use `webis`), use
Johannes Kiesel's avatar
Johannes Kiesel committed
36

37
```
Johannes Kiesel's avatar
Johannes Kiesel committed
38
./webis.py core install
39 40
```

Johannes Kiesel's avatar
Johannes Kiesel committed
41 42
### Bash Completion 
After installation, add the following to your `.bashrc`:
43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66
```
# WEBIS CMD START
_completewebis() {
  COMPREPLY=()
  local incomplete_word="${COMP_WORDS[COMP_CWORD]}"
  local complete_words=("${COMP_WORDS[@]:0:${#COMP_WORDS[@]}-1}")
  # Check if webis offers usage instructions without the incomplete word
  if [ $(${complete_words[@]} -h 2> /dev/zero | head -n 1 | grep "^usage: " | wc -l) -eq 1 ];then
    # Get positional arguments
    available_words=$(${complete_words[@]} -h | grep "^    [^ ]" | awk '{print $1}')
    COMPREPLY=($(compgen -W '$available_words' -- "$incomplete_word"))
  else
    # Normal file completion
    COMPREPLY=($(compgen -f ${incomplete_word}))
  fi
}
complete -F _completewebis webis
# WEBIS CMD END
```
and `source .bashrc` it. You should now be able to use tab-completion with `webis`.

The tab completion works by using the `-h` flag. It appends `-h` to the completed part of the command and checks if this returns a message starting with `usage: `. It then offers all arguments for completion that this usage prints, where arguments identified by lines with four leading spaces. If your script within the command adheres to this output for `-h`, tab completion could automatically work, as well.


Johannes Kiesel's avatar
Johannes Kiesel committed
67 68
## Extending `webis`
### Configuration
69 70 71 72 73 74 75 76 77 78 79
See: `config.json`

```
    {
        "commands_directory": "tools/",
        "allowed_scripts": ["python", "bash"],
        "ignored_dirs": ["CVS"],
        ....
    }
```

Johannes Kiesel's avatar
Johannes Kiesel committed
80
### Commands directory (tools)
81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108
Structure of an example `test` command:

```
├── core
│   ├── checker.sh
│   ├── install.sh
│   └── remove.sh
└── test
    ├── a.sh
    ├── b
    ├── t.oy
    └── t.txt
```

`core` and `test` are metanames for each toolkit, a call to

```
./webis.py core -h
```

will print a short summary of all tools.

```
./webis.py core checker
```

will perform a code style check of the tools directory

Johannes Kiesel's avatar
Johannes Kiesel committed
109
### Adding a new command
110 111 112 113 114 115 116 117 118 119 120 121 122
First create a new folder `FOLDER` in the `tools` directory and add all
scripts to this folder, e.g. `MYSCRIPT.py` and test it:

```
./webis.py FOLDER MYSCRIPT
./webis.py FOLDER -h
./webis.py -h
```

Add a description of the command in the `"commands_help"` section of the
`config.json` configuration file. You can also add shortcut aliases in
`"commands_aliases"`.

123 124 125
To update the cheatsheet.md, run `webis core update-cheatsheet` and then commit
the changes together with the new command.

Johannes Kiesel's avatar
Johannes Kiesel committed
126
#### Code conventions for command scripts
127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145
Inside a command directory, every script should have a small
descriptive comment, e.g.:

```
#!/usr/bin/env bash
# General description
#
# Copyright 2015-today
#
# Project WEBIS
# Author: Your Name
#
# Requires: tool requirements here

```

It is important for the `./webis.py NAME -h` call that this comment is
the second line of the script, this approach can be seen as a extension of shebang.

Johannes Kiesel's avatar
Johannes Kiesel committed
146
#### General scripts
Johannes Kiesel's avatar
Johannes Kiesel committed
147
All scripts must be code style checked with the `webis core checker`
148 149 150
command. For python scripts this checks `pep8` code style and for bash it
checks the Google Bash style conventions.

Johannes Kiesel's avatar
Johannes Kiesel committed
151
#### Bash scripts
152 153
Use the `bashhelper` functions (`logInfo`, `logError`, `yes_no_prompt`, ...) if possible.

Johannes Kiesel's avatar
Johannes Kiesel committed
154
#### Python scripts
155 156 157 158 159 160 161
Use `libs.log` for uniform console output and to avoid reinventing the wheel.
Organize imports of each Python script in the following way:

1. python standard libraries
2. thirdparty imports
3. own imports

Johannes Kiesel's avatar
Johannes Kiesel committed
162
### Possible problems for new commands
163 164 165 166
* Usage of hard coded paths, see `core/install.sh` for path handling
* Usage of local imported files. `webis` will not change to the working
  directory of the script, but work from the `webis` root directory
* Don't create a `help.{py,sh}` script inside a module