doc/plugins.md in power_stencil-0.7.4 vs doc/plugins.md in power_stencil-0.8.0

- old
+ new

@@ -13,10 +13,12 @@ - [Plugin creation](#plugin-creation) - [Adding new subcommands to `PowerStencil`](#adding-new-subcommands-to-powerstencil) - [Providing entity types and templates](#providing-entity-types-and-templates) - [Providing custom build process](#providing-custom-build-process) - [Plugin capabilities and structure](#plugin-capabilities-and-structure) + - [Proposed default plugin structure and life-cycle](#proposed-default-plugin-structure-and-life-cycle) + - [Fully manually created plugin](#fully-manually-created-plugin) - [Using plugins available as gems](#using-plugins-available-as-gems) - [Conclusion](#conclusion) <!-- /TOC --> [:back:][Documentation root] @@ -44,16 +46,16 @@ # What are plugins ? Plugins are actually Ruby Gems with a specific structure. Plugins can be part of the project or provided as a separated stand-alone Gem. -The normal process would be to begin with a plugin within the project and once you're ok with its features you may release it as a standalone Ruby Gem. +The normal process would be to begin with a plugin within the project (under `.ps_project/plugins` directory) and once you're ok with its features you may release it as a standalone Ruby Gem. - Plugins local to the project are automatically taken in account. -- To use plugins provided as Gems you have to set the `:plugins:` array property in the `.ps_project/versioned-config.yaml` +- To use plugins provided as Gems you have to set the `:project_plugins:` array property in the `.ps_project/versioned-config.yaml` -:warning: Plugins provided as standalone Gems are not thoroughly tested, for the time being, you may use plugins local to the project. +See [using plugins gems](#using-plugins-available-as-gems) for more information. # Creating plugin local to the project ## Plugin creation @@ -158,14 +160,16 @@ * init: Initializes a PowerStencil repository ... * info: Generic information about the repository ... * plugin: Manipulates plugins ... * get: Query entities from repository ... * shell: Opens a shell to interact with entities ... + * adm: Administrative commands ... * check: Check repository entities consistency ... * create: Creates entities in the repository ... * edit: Edit entities from repository ... * delete: Delete entities from repository ... + * describe: Detailed information about entity types ... * build: Builds entities ... * myplugin: Does nothing useful Added by plugin myplugin ``` You can see that the plugin brought a new sub-command `myplugin`. @@ -308,16 +312,28 @@ Here the code simply reads the generated `message.txt` file and displays it... # Plugin capabilities and structure -So the `power_stencil plugin --create` generated a fully working plugin, implementing all the features (actually for the time being only custom dsl is not yet implemented) you could define in a template. +## Proposed default plugin structure and life-cycle -The generated plugin has the structure of a legit ruby gem, and this is not by chance, this is to prepare the fact that you may want to create a stand-alone plugin gem that you you may want to re-use in different projects. +So the `power_stencil plugin --create` generated a fully working plugin, implementing all the features you could define in a plugin. -But this is not mandatory. Actually the only mandatory file for a plugin to be valid is the file `etc/plugin_capabilities.yaml` in the plugin directory. This file declares what the plugin is able to do. For the `myplugin` we just created it contains: +The generated plugin has the structure of a legit ruby gem, and this is not by chance, this is to prepare the fact that you may want to create a _stand-alone plugin gem_ that you you may want to re-use accross different projects. +So, the default structure of a generated plugin is a very good starting point to develop your own plugins. You may remove manually some of the features, add some... and then eventually decide to separate it from your project repository, give it its own life and release it as a `PowerStencil` gem plugin. :champagne: :stars: + +**:information_source:This is by far the easiest and safest way to create and make evolve plugins of your own and the recommended way.** + + +## Fully manually created plugin + + +Nevertheless and in order to further understand the concepts behind `PowerStencil` plugins, here under you will find a way to do everything manually. + +Using the provided plugin template is not mandatory. Actually the only mandatory file for a plugin to be valid is the file `etc/plugin_capabilities.yaml` in the plugin directory. This file declares what the plugin is able to do. For the `myplugin` we just created it contains: + ```yaml --- # This file defines the capabilities exposed by the plugin. This file is mandatory # for a plugin to be considered as valid. @@ -360,11 +376,11 @@ Let's create a plugin fully manually instead of using the `power_stencil plugin --create`. From the root of the project, let's create the directory: $ mkdir -p .ps_project/plugins/minimal/etc -(of course the command to create the directory may be different on your system). Then here let's create a `plugin_capabilities.yaml` file with the following content: +(of course the command to create the directory may be different on your system). Then here let's create a `plugin_capabilities.yaml` file in this `etc` subdirectory of the plugin directory with the following content: ```yaml --- :plugin_module: null :processors: null @@ -424,17 +440,17 @@ :type: :minimal :fields: :name: test ``` -All of this to demonstrate that a plugin can be almost anything, even something very minimalistic, but nevertheless you should keep on using the `power_stencil plugin --create` command and benefit from the structure it brings, as well as the possibility to become a stand-alone plugin gem... +All of this to demonstrate that a plugin can be almost anything, even something very minimalistic, but nevertheless **you should keep on using the `power_stencil plugin --create` command and benefit from the structure it brings, as well as the possibility to become so easily a stand-alone plugin gem**... # Using plugins available as gems -Any plugin you have created using the `power_stencil plugin --create` command is directly eligible to become a gem. +Any plugin you have created using the `power_stencil plugin --create` command is directly eligible to become a plugin gem. -**If you release a plugin you created within a project as a gem (by doing `bundle exec rake release` from within the plugin directory, like for any standard gem :+1:), you can then re-use your plugin from any other `PowerStencil` project !** +**If you release a plugin you created within a project as a gem (by doing `bundle exec rake release` from within the plugin directory, like for any standard gem :+1:), you can then re-use your plugin accross any other `PowerStencil` project !** All you have to do for that is to declare it in the `.ps_project/versioned-config.yaml` config file by adding an array `:project_plugins`: ```yaml ... @@ -471,10 +487,10 @@ Installed plugin 'my_awesome_plugin1' (version: 0.1.0) Installed plugin 'my_awesome_plugin2' (version: 0.1.1) Installed plugin 'my_awesome_plugin3' (version: 1.2.3) ``` -**:star2: ::+1: You can now verify using `power_stencil info` or `power_stencil plugin --list`, that the plugins have been installed and that any feature they provide is now available to your project.** +**:star2: ::+1: You can now verify using `power_stencil info` or `power_stencil plugin --list -v`, that the plugins have been installed and that any feature they provide is now available to your project.** # Conclusion The documentation for plugins is not fully complete, so you are encouraged to read the code. Some official plugins are under development, and the documentation will be improved along their development... \ No newline at end of file