Cleanup part 1

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

_test_in.py

@@ -1,5 +0,0 @@
-#!/usr/bin/python
-
-import sys
-
-print("=> " + sys.stdin.read())

_test_out.py

@@ -1,4 +0,0 @@
-#!/usr/bin/python
-
-for i in range(0, 5):
-    print("\033[91mHello World!")

pyproject.toml

@@ -19,7 +19,7 @@ requires-python = ">=3.11"
 
 [project.urls]
 Homepage = "https://forge.monodon.me/Gnarwhal/sshare"
-Documentation = "https://forge.monodon.me/Gnarwhal/sshare/README.md#Usage"
+Documentation = "https://forge.monodon.me/Gnarwhal/sshare/README.md"
 Repository = "https://forge.monodon.me/Gnarwhal/sshare"
 Issues = "https://forge.monodon.me/Gnarwhal/sshare/issues"
 

tests/test_test.py

@@ -1,4 +0,0 @@
-from src.sshare.plugin.config import Argument
-
-def test_foo():
-    assert True