From 2cd73d2ded3a3a207a9c089e232af08a0b244f39 Mon Sep 17 00:00:00 2001 From: Federica Brando Date: Mon, 18 Mar 2024 12:25:11 +0100 Subject: [PATCH] add: documentation for new plugin system --- docs/examples/cli/main_cli.ipynb | 228 ++++++++++++++++-------------- docs/user_guide/cli.rst | 4 +- docs/user_guide/plugin_system.rst | 5 +- 3 files changed, 126 insertions(+), 111 deletions(-) diff --git a/docs/examples/cli/main_cli.ipynb b/docs/examples/cli/main_cli.ipynb index f599f3d..dd58f6b 100644 --- a/docs/examples/cli/main_cli.ipynb +++ b/docs/examples/cli/main_cli.ipynb @@ -2,49 +2,55 @@ "cells": [ { "cell_type": "markdown", - "source": [ - "# Main tasks" - ], "metadata": { "collapsed": false, "pycharm": { "name": "#%% md\n" } - } + }, + "source": [ + "# Main tasks" + ] }, { "cell_type": "markdown", + "metadata": { + "collapsed": false, + "pycharm": { + "name": "#%% md\n" + } + }, "source": [ "We can run the main tasks that **OpenVariant** offers as a Python package, also, with a shell command. In [Introduction section](./introduction_cli.ipynb) you can check which are the different commands and their options.\n", "\n", "In the following examples we will see a little snip on these tasks.\n", "\n", "--------" - ], + ] + }, + { + "cell_type": "markdown", "metadata": { "collapsed": false, "pycharm": { "name": "#%% md\n" } - } - }, - { - "cell_type": "markdown", + }, "source": [ "### ***Cat*** command\n", "\n", "A simple case of the command:" - ], - "metadata": { - "collapsed": false, - "pycharm": { - "name": "#%% md\n" - } - } + ] }, { "cell_type": "code", "execution_count": 1, + "metadata": { + "collapsed": false, + "pycharm": { + "name": "#%%\n" + } + }, "outputs": [ { "name": "stdout", @@ -74,58 +80,58 @@ "source": [ "%%bash\n", "openvar cat ../datasets/sample2" - ], - "metadata": { - "collapsed": false, - "pycharm": { - "name": "#%%\n" - } - } + ] }, { "cell_type": "markdown", - "source": [ - "Using it with some flags:" - ], "metadata": { "collapsed": false, "pycharm": { "name": "#%% md\n" } - } + }, + "source": [ + "Using it with some flags:" + ] }, { "cell_type": "code", "execution_count": 2, - "outputs": [], - "source": [ - "%%bash\n", - "openvar cat ../datasets/sample2 --output ./output_cat_cmd.tsv --header" - ], "metadata": { "collapsed": false, "pycharm": { "name": "#%%\n" } - } + }, + "outputs": [], + "source": [ + "%%bash\n", + "openvar cat ../datasets/sample2 --output ./output_cat_cmd.tsv --header" + ] }, { "cell_type": "markdown", - "source": [ - "### ***Count*** command\n", - "\n", - "A simple case of the command:" - ], "metadata": { "collapsed": false, "pycharm": { "name": "#%% md\n" } - } + }, + "source": [ + "### ***Count*** command\n", + "\n", + "A simple case of the command:" + ] }, { "cell_type": "code", "execution_count": 3, + "metadata": { + "collapsed": false, + "pycharm": { + "name": "#%%\n" + } + }, "outputs": [ { "name": "stdout", @@ -138,29 +144,29 @@ "source": [ "%%bash\n", "openvar count ../datasets/sample2 -q" - ], - "metadata": { - "collapsed": false, - "pycharm": { - "name": "#%%\n" - } - } + ] }, { "cell_type": "markdown", - "source": [ - "Using it with some flags:" - ], "metadata": { "collapsed": false, "pycharm": { "name": "#%% md\n" } - } + }, + "source": [ + "Using it with some flags:" + ] }, { "cell_type": "code", "execution_count": 4, + "metadata": { + "collapsed": false, + "pycharm": { + "name": "#%%\n" + } + }, "outputs": [ { "name": "stdout", @@ -182,17 +188,17 @@ "source": [ "%%bash\n", "openvar count ../datasets/sample2 --group_by \"SYMBOL\" --cores 4 -q" - ], + ] + }, + { + "cell_type": "code", + "execution_count": 5, "metadata": { "collapsed": false, "pycharm": { "name": "#%%\n" } - } - }, - { - "cell_type": "code", - "execution_count": 5, + }, "outputs": [ { "name": "stdout", @@ -214,31 +220,31 @@ "source": [ "%%bash\n", "openvar count ../datasets/sample2 --group_by \"SYMBOL\" --where \"CANCER == 'ACC'\" --cores 4 -q" - ], - "metadata": { - "collapsed": false, - "pycharm": { - "name": "#%%\n" - } - } + ] }, { "cell_type": "markdown", - "source": [ - "### ***Group by*** command\n", - "\n", - "A simple case of the command:" - ], "metadata": { "collapsed": false, "pycharm": { "name": "#%% md\n" } - } + }, + "source": [ + "### ***Group by*** command\n", + "\n", + "A simple case of the command:" + ] }, { "cell_type": "code", "execution_count": 6, + "metadata": { + "collapsed": false, + "pycharm": { + "name": "#%%\n" + } + }, "outputs": [ { "name": "stdout", @@ -270,29 +276,29 @@ "source": [ "%%bash\n", "openvar groupby ../datasets/sample2 -g \"CANCER\" --show --header -q" - ], - "metadata": { - "collapsed": false, - "pycharm": { - "name": "#%%\n" - } - } + ] }, { "cell_type": "markdown", - "source": [ - "Using it with some flags:" - ], "metadata": { "collapsed": false, "pycharm": { "name": "#%% md\n" } - } + }, + "source": [ + "Using it with some flags:" + ] }, { "cell_type": "code", "execution_count": 7, + "metadata": { + "collapsed": false, + "pycharm": { + "name": "#%%\n" + } + }, "outputs": [ { "name": "stdout", @@ -306,17 +312,17 @@ "source": [ "%%bash\n", "openvar groupby ../datasets/sample2 -g \"CANCER\" --where \"SYMBOL == 'ATAD3C'\" --cores 4 --show -q" - ], + ] + }, + { + "cell_type": "code", + "execution_count": 8, "metadata": { "collapsed": false, "pycharm": { "name": "#%%\n" } - } - }, - { - "cell_type": "code", - "execution_count": 8, + }, "outputs": [ { "name": "stdout", @@ -336,45 +342,53 @@ "source": [ "%%bash\n", "openvar groupby ../datasets/sample2 -g \"CANCER\" --script \"grep -E -i '^(B3|ATA)'\" --show --cores 4 -q" - ], + ] + }, + { + "cell_type": "markdown", "metadata": { "collapsed": false, "pycharm": { - "name": "#%%\n" + "name": "#%% md\n" } - } - }, - { - "cell_type": "markdown", + }, "source": [ "\n", "### ***Plugin*** command\n", "\n", "_Plugin_ is slightly different than the others commands.\n", "\n", - "On this one we have only one single action: `create`." - ], - "metadata": { - "collapsed": false, - "pycharm": { - "name": "#%% md\n" - } - } + "On this one we have only one single action: `create`. \n", + "The plugin will use the environment variable `OPENVAR_PLUGIN` directory where to store new plugins.\n", + "\n", + "by default:\n", + "\n", + "```sh\n", + "OPENVAR_PLUGIN=/home/user/.local/share/openvariant\n", + "```\n", + "\n", + "default directory can be changed by exporting a new path to OPENVAR_PLUGIN variable.\n", + "\n", + "i.e.\n", + "```sh\n", + "export OPENVAR_PLUGIN=/my/plugin/path/\n", + "```" + ] }, { "cell_type": "code", "execution_count": null, - "outputs": [], - "source": [ - "%%bash\n", - "openvar plugin create --name add_date --directory ../plugin_system" - ], "metadata": { "collapsed": false, "pycharm": { "name": "#%%\n" } - } + }, + "outputs": [], + "source": [ + "%%bash\n", + "openvar plugin create --name add_date" + ] } ], "metadata": { @@ -398,4 +412,4 @@ }, "nbformat": 4, "nbformat_minor": 0 -} \ No newline at end of file +} diff --git a/docs/user_guide/cli.rst b/docs/user_guide/cli.rst index 7df0326..a9a743e 100644 --- a/docs/user_guide/cli.rst +++ b/docs/user_guide/cli.rst @@ -97,11 +97,11 @@ Create -------- It will generate the template with required files to apply and run a new plugin with the name stipulated and in the -corresponding directory. +default directory. .. code-block:: bash # Example - openvar plugin create -n reverse_value -d /my_plugins + openvar plugin create -n reverse_value For further details, check :ref:`Command-line interface examples` and you will have a clearer picture on how to use CLI tasks. \ No newline at end of file diff --git a/docs/user_guide/plugin_system.rst b/docs/user_guide/plugin_system.rst index 5e0d920..e0fbb41 100644 --- a/docs/user_guide/plugin_system.rst +++ b/docs/user_guide/plugin_system.rst @@ -19,8 +19,9 @@ visualize how the different classes are connected and composed with **OpenVarian | -As we have mentioned before, the plugin has to be present on the `annotation` file in order to be used. Plugins can be -distributed on different folders where `Builder` will manage to find them and apply the data transformation. +As we have mentioned before, the plugin has to be present on the `annotation` file in order to be used. Custom plugins will be placed in the +folder where the environment variable `OPENVAR_PLUGIN` points (`/home/user/.local/openvariant/` by default). +The `Builder` will manage to find them and apply the data transformation. Plugins will inherit `Context` and `Plugin` as base classes for each plugin. These classes are described as it follows: **Context**