diff --git a/README.md b/README.md index 38b03cc..aa8c6aa 100644 --- a/README.md +++ b/README.md @@ -2,11 +2,6 @@ Upload files to a server via ssh -## Documentation - -- **End User**: coming soon... -- **Plugin Developer**: coming soon... - ## Installing SSHare is not available on [PyPI](https://pypi.org). @@ -23,7 +18,151 @@ Beyond that it only utilises the python standard library. ### Additional Functionality The base install is fairly bare bones in terms of functionality. -Included in the [`examples/`](https://forge.monodon.me/Gnarwhal/sshare_plugins) submodule, there are included some +Included in the [`examples/`](https://forge.monodon.me/Gnarwhal/sshare_plugins) submodule, there is a sampling of plugins which provide some additional conveniences -Refer to \[coming soon...\] for information on installing plugins +Refer to the above documentation for information on installing plugins + +## Documentation - End User + +Getting started with SSHare is about getting familiar with configuring SSHare. +SSHare configuration is all done in the `${XDG_CONFIG_DIR}/sshare` if set, or in `~/.config/sshare` otherwise. +In this directory are two important items: the `config.toml` file and the `plugins/` directory. + +### `plugins/` + +The `plugins/` directory is home to all external plugins. Installing a plugin is as simple as saving the +the plugin's `.py` file to the `plugins/`. + +### `config.toml` + +The configuration file can be broken down into three major components: `spec`, `config`, and `flags`. + +#### `spec` + +```toml + +[spec.default] +name = [ "time", "extension" ] + +[spec.example] +flag = { short = "e", long = "example" } +name = [ "preserve", "extension" ] + +[spec.noshort] +flag = { long = "only" } +name = [ "time" ] +help = "No short flag, only long flag >:(" +``` + +The `spec` section is a collection of different runtime specifications. The name of a specification is +unimportant with the exception of `default`, which is run when no other spec is activated. In each specification +that isn't `default`, there is a `flag` attribute that sets which command line arguments activate the +specification. The `flag` attribute must have one or both of `short` or `long`, where `short` will be set the flag +`-{short}` and `long` will set the flag `--{long}`. The `name` attribute of a specification is an array of name type +plugins which controls the order in which said plugins are executed. Specifications can also provide a brief description +in the `help` attribute, which will be displayed when `sshare --help` is run. In the example above, +running `sshare --help` would give +``` +options: + -e, --example Use example spec + --only No short flag, only long flag >:( +``` +#### `config` + +```toml +[config.ssh] +host = "example.com" +path = "/directory/to/store/files/in" +port = 22 +``` + +The `config` section is used to set configuration options for plugins. Refer to documentation for a plugin to see +what options can be set here. Documentation for default plugins is included [below](#Default-Plugins). + +#### `flags` + +```toml +[flags.file] +file = { short = "f" } + +[flags.stdin] +stdin = { short = "" } + +[flags.example] +option = { short = "o", long = "ooooption" } +``` + +The `flags` section is used to bind plugin arguments to a command line argument. They are specified in the same way +as the `flag` option for `spec`s. If `long` is left unspecified, the long flag will be set to the default provided by +the plugin. In the example above, running `sshare --help` would give: +``` +options: + -f file, --file file Upload a file + -, --stdin Upload from stdin + -o xmpl, --ooooption xmpl + This is not a real plugin that exists +``` + +### Default Plugins + +#### `command_line` + +A `logger` plugin which prints to the command line. No configuration needed. + +#### `extension` + +A `name` plugin which appends the source type to the end of the file name (i.e. `txt`, `png`, etc...). No configuration needed. + +#### `file` + +A `source` plugin which provides a file to be uploaded. File is specified with the `--file {file_path}` argument. No configuration needed. + +#### `preserve` + +A `name` plugin which preserves the name of the source in the uploaded file. No configuration needed. + +#### `print_location` + +A `feedback` plugin which prints the location that sources can be accessed from. No configuration needed. + +#### `ssh` + +An `upload` plugin which uploads the sources to the server using `ssh`. + +##### Configuration +| Attribute | Type | Default | Description | +|-----------|--------|---------|------------------------------------------------------| +| host | string | None | The hostname to ssh into | +| path | string | None | The path of the directory to upload the sources into | +| port | int | 22 | The port to ssh into | +| user | string | $USER | The user to ssh as | + +#### `stdin` + +A `source` plugin which reads from stdin. No configuration needed. + +#### `time` + +A `name` plugin which adds the current unix time to the name of the of the uploaded file. + +##### Configuration +| Attribute | Type | Default | Description | +|-----------|--------|---------|------------------------------------------------------| +| format | int | 62 | The base between 2 and 62 to represent the number in | + +##### `uri` + +A `location` plugin which constructs the resulting URI that the uploaded file can be accessed from. + +##### Configuration +| Attribute | Type | Default | Description | +|-----------|--------|---------|------------------------------------------------------| +| protocol | string | https | The protocol of the URI | +| host | string | None | The hostname the file can be accessed from | +| port | int | 22 | The port the file can be accessed at | +| path | string | None | The path the file can be accessed at | + +## Documentation - Plugin Development + +Coming soon... diff --git a/_test_in.py b/_test_in.py deleted file mode 100755 index 572e9d1..0000000 --- a/_test_in.py +++ /dev/null @@ -1,5 +0,0 @@ -#!/usr/bin/python - -import sys - -print("=> " + sys.stdin.read()) diff --git a/_test_out.py b/_test_out.py deleted file mode 100755 index f89bd5d..0000000 --- a/_test_out.py +++ /dev/null @@ -1,4 +0,0 @@ -#!/usr/bin/python - -for i in range(0, 5): - print("\033[91mHello World!") diff --git a/tests/test_test.py b/tests/test_test.py deleted file mode 100644 index 3c71169..0000000 --- a/tests/test_test.py +++ /dev/null @@ -1,4 +0,0 @@ -from src.sshare.plugin.config import Argument - -def test_foo(): - assert True