power_stencil 0.8.13 → 0.9.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 658cd6b4a3099ebad88b964d3d2d29125e2d2632
-  data.tar.gz: d4593e14e6b18d7dcd7888881d4ab8e2cc0188d7
+  metadata.gz: c36f08f7b3ad9a916e27a18e755af6794084b97f
+  data.tar.gz: 82104cf2bda5b15f57020b57ccf66b1e95ee241c
 SHA512:
-  metadata.gz: e8907db7dd9cc04235d905999303b07d643cfd4907cbfb9f67f3efd1eb56469a2436853bb626745f1e768daab7588e951890975fc2614f860876c27d145a8758
-  data.tar.gz: 95a384be8f2a4587af1c46710fdbf6ad10024d439a41c4f96889dfbdf57eb7dcf2ac8860e2f08ccf0e4d0d213a5f2fc957b4d5340d51efa905ada5566701386c
+  metadata.gz: 6d1db8dd8989c9299eea8fe869e527f7c86b93db49353962ecf2620a34614fb143a39b02e12480dd02929c57c5adce19ec53b35754e327e79c9620bff0d1708f
+  data.tar.gz: 8e1377704873ca6d8a8eb69c4ba7e41f3e2a9cb0af77b3c7d06ea5bb5fc3174b72dc3df81140dcbd4cb0c286b21bac3ebc7e15fff4ff44d82e4e08acc5925e31

data/README.md

@@ -15,10 +15,10 @@ See [official website][PowerStencil site].
 - [Installation](#installation)
 - [Usage](#usage)
     - [Help](#help)
-    - [Command line auto-completion](#command-line-auto-completion)
-    - [Creating a `PowerStencil` project](#creating-a-powerstencil-project)
-    - [`PowerStencil` project structure](#powerstencil-project-structure)
     - [Getting started](#getting-started)
+        - [Creating a `PowerStencil` project](#creating-a-powerstencil-project)
+        - [`PowerStencil` project structure overview](#powerstencil-project-structure-overview)
+        - [Command line auto-completion](#command-line-auto-completion)
         - [Entities](#entities)
         - [Templates](#templates)
         - [Builds](#builds)
@@ -62,11 +62,12 @@ The `PowerStencil` gem provides the `power_stencil` executable which is a plugga
 
 **Actually `PowerStencil` is _not_ a templating engine**. It uses already existing and proven templating engines.
 
-Currently it uses [ERB], which is a pretty standard and very well known engine in the [Ruby] world and especially for people who already used the [Rails] framework. Virtually any templating engine existing in the Ruby ecosystem could be integrated in the `PowerStencil` framework next to [ERB] (as `PowerStencil` already comes with a mechanism to select a templating engine regarding some criteria like file extension, path etc...). 
+`PowerStenil` currently embeds two templating engines:
 
-This will probably be the case in a future release, at least to integrate the [Haml] templating engine in order to ease the generation of XML-like files, still you obviously already can do it with [ERB].
+* **[ERB] is the default**. This is a pretty standard and very well known engine in the [Ruby] world and especially for people who already used the [Rails] framework. This is a generic templating engine which can handle any use-case. Each template will be processed by default using the [ERB] engine.
+* When it comes to generate mark-up documents like XML or HTML, many people prefer to use [Haml], as it designed towards generating these kinds of documents and tends to end-up with much clearer templates. Any template whose names ends by `.haml` will be processed by the [Haml] engine by default instead of [ERB].
 
-So `PowerStencil` is definitely not a templating it is actually much more than that.
+So `PowerStencil` is definitely not a templating engine, it is actually much more than that. It is a framework to manage your templates, design the relational data you can use in your templates, manage the versioning, define the way you build things etc... Read this documentation (and especially the [getting started](#getting-started) section which is a tutorial in itself).
 
 
 # Installation
@@ -134,17 +135,16 @@ The program uses the standard paradigm of sub-commands (à-la-git), and each can
 
 [Plugins] may bring extra subcommands and/or options, so depending on the project you are working in, the output of `--help` may differ...
 
-## Command line auto-completion
 
-`PowerStencil` comes with a command-line auto-completion feature for `zsh`. It is not yet available for `bash`.
 
-You can install it by running:
 
-    $ power_stencil adm --zsh-completion
 
-It provides a very useful auto-completion for sub-commands, options as well as parameters...
+## Getting started
+
+See the following topics as a kind of tutorial on `PowerStencil`. You should read them in order, as each of them assumes you already read the previous one.
 
-## Creating a `PowerStencil` project
+
+### Creating a `PowerStencil` project
 
 To create a new project, use the `init` sub-command. It works as you would expect. If you run it in an existing directory it will create the project here but you can specify the directory where you want the project to be created (the path will be created provided you have enough rights on the filesystem):
 
@@ -156,7 +156,7 @@ Once the project created, if you are anywhere within the project tree, you don't
 
 **:information_source: If you have `git` installed on your system, **the repository of the newly created project has been automatically turned into a git repository. And any action done through the `power_stencil` command-line will be automatically tracked by `git`**. Only things you will do outside of the `power_stencil` command-line (adding or modifying templates, creating or modifying entity types... any manual action) will require a user action to make `git` take it in account. You can completely de-activate this behaviour if you want to fully manage things by yourself by adding `:no-git: true` in the `.ps_project/versioned-config.yaml`, yet there is no good reason for that... Unless you know what you are doing, you should keep the default settings. See [Git integration] for further information.
 
-## `PowerStencil` project structure
+### `PowerStencil` project structure overview
 
 The structure of a brand new `PowerStencil` project is the following:
 
@@ -191,9 +191,21 @@ There is the same mechanism between `.ps_project/entities` (where the project da
 
 The `plugins` directory can optionally contain project specific plugins. Plugins are a great way to extend `PowerStencil` for the needs of a project or organization.
 
-## Getting started
+### Command line auto-completion
+
+`PowerStencil` comes with a powerful command-line auto-completion feature for `zsh`. (It is not yet available for `bash`).
+
+You can install it by running:
+
+    $ power_stencil adm --zsh-completion
+
+It provides a very useful auto-completion for sub-commands, options as well as options parameters...
+
+`PowerStencil` uses a _two-stages_ auto-completion mechanism:
+
+* Project independent completion is generated in `~/.zsh/completion/_power_stencil`, whereas completion related to new commands or options, coming from plugins used in a project, is generated (and versioned) within the project itself, in `.ps_project/.zsh_project_completion`.
 
-See the four following topics as a kind of tutorial on `PowerStencil`. You should read them in order, as each of them assumes you already read the previous one.
+* Meaning that if you want to benefit from the "_full_" completion from within a project you may have to re-run `power_stencil add --zsh-completion` from within any project where you use extra plugins, in order to generate that `.ps_project/.zsh_project_completion` file. If you don't, it is not a big deal, but then you will only have access to the "_generic_" completion, ie completion not taking in account any of the extra commands or options you are using in this project brought by plugins you may use...
 
 ### Entities
 

data/doc/faq.md

@@ -72,12 +72,13 @@ I had the opportunity to have access to a Windows VM and tested `PowerStencil`.
 
 # What is the status of `PowerStencil` ?
 
-`PowerStencil` is still under development, yet **it can already be safely used**.
+`PowerStencil` is still considered under development until version `1.0.0` is released, yet **it can already be safely used**, event for production.
+
+**Since it entered the `0.9.x` version, no new feature should be added**. That branch will be used for statibilisation and anything released there should only be related to bugfixes, and plugin developement. As a bunch of official plugins should be released along with the version `1.0.0`.
 
 Regarding `PowerStencil` core:
 
-- The part that may evolve the most is the plugin part (including documentation which is not really in par with the rest...), but it should not break anything developed now.
-- New system entity types may appear.
+- The plugin related features may still evole a bit along with first official plugins development, but since both local and gems plugins are supported no big change may arise in the architecture.
 - The functional documentation is evolving.
 - There is almost no technical/architectural documentation yet. Read the code...
 
@@ -85,10 +86,6 @@ Anyway `PowerStencil` follows the semantic versioning pattern and if incompatibl
 
 There are already some plugins in the pipe. See [example use cases], to get an idea of the first official plugins to come.
 
-:information_source: Of course, `PowerStencil` is new software and it is expected to evolve with the needs of its users...
-
-
-
 
 [:back:][Documentation root]
 <!-- End of Document -->

data/doc/git_integration.md

@@ -13,6 +13,7 @@ Git integration
     - [Deleting an entity](#deleting-an-entity)
     - [`PowerStencil` shell session](#powerstencil-shell-session)
     - [Plugin creation](#plugin-creation)
+    - [(Re)Generating `zsh` command line completion for the project](#regenerating-zsh-command-line-completion-for-the-project)
 - [Manual actions](#manual-actions)
 
 <!-- /TOC -->
@@ -36,18 +37,19 @@ Here is a summary:
 
 | `PowerStencil` sub-command | Status |
 |----------------------------|:------:|
-|init        | creates a project
-|info        | read-only
-|plugin      | creates a plugin
-|get         | read-only
-|shell       | do anything  
-|adm         | read-only
-|check       | read-only  
-|create      | creates entities
-|edit        | modifies entities
-|delete      | deletes entities
-|describe    | read-only
-|build       | read-only  
+|`init`                      | creates a project
+|`info`                      | read-only
+|`plugin`                    | creates a plugin
+|`get`                       | read-only
+|`shell`                     | do anything  
+|`adm --zsh-completion`      | generates zsh command-line completion
+|`check`                     | read-only  
+|`create`                    | creates entities
+|`edit`                      | modifies entities
+|`delete`                    | deletes entities
+|`describe`                  | read-only
+|`build`                     | read-only  
+
 
 On top this we could add some other actions, you can obviously perform manually within the repository, like:
 
@@ -306,6 +308,30 @@ Date:   Sun Nov 3 19:42:11 2019 +0100
 Cool ! Nevertheless, plugins may be one of the things you may want to track a bit differently. For example as git sub-modules, to keep a separated git history, and ease future re-useability of the plugin you are developing.
 So it's up to you and `PowerStencil` provides an easy way to keep your plugin out of your project repo. Same as for `power_stencil init`, `power_stencil plugin --create` supports the `--no-git` option...
 
+## (Re)Generating `zsh` command line completion for the project
+
+If you generate the zsh command line completion file for the project by doing, from within the project:
+
+    $ power_stencil adm --zsh-completion
+
+You will then generate a file that contains project-specific zsh completion directives: `.ps_project/.zsh_project_completion`.
+
+That file is versioned too, because its content depends on the plugins (local or as gems) that you actually use in this project. **If you add a new plugin or modify the way local ones handle the command-line, you should then regenerate it**, by re-running that command if you want the completion to fully take in account your changes.
+
+It is tracked like that:
+```
+$ git log -1 --summary
+commit 0c7bedb7249654873882c56bb15172c528511cff
+Author: Joe <joe@outerspace.org>
+Date:   Sun Nov 10 11:21:10 2019 +0100
+
+    Adding project specific zsh completion file: '.ps_project/.zsh_project_completion'.
+
+ create mode 100644 .ps_project/.zsh_project_completion
+```
+
+
+
 # Manual actions
 
 Ok, so far we have a pretty nice git history:

data/etc/meta_templates/plugin_seed/.gitignore

@@ -0,0 +1,12 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+/.idea/
+Gemfile.lock
+# rspec failure tracking
+.rspec_status

data/etc/meta_templates/plugin_seed/.gitlab-ci.yml

@@ -0,0 +1,11 @@
+image: "ruby:2.3"
+
+before_script:
+  - gem install bundler --no-document
+  - bundle install --jobs $(nproc)  "${FLAGS[@]}"
+  - git config --global user.email "noone@nowhere.org"
+  - git config --global user.name "Testman"
+
+rspec:
+  script:
+    - bundle exec rspec

data/etc/meta_templates/plugin_seed/README.md

@@ -2,7 +2,7 @@
 <%= plugin_title_name %>
 <%= '=' * plugin_title_name.size %>
 
-[![Gem Version](https://badge.fury.io/rb/<%= gem_name %>.svg)](https://rubygems.org/gems/<%= gem_name %>) [![Pipeline status](https://gitlab.com/tools4devops/psplugins/<%= gem_name %>/badges/master/pipeline.svg)](https://gitlab.com/tools4devops/psplugins/<%= gem_name %>/commits/master)
+[![Gem Version](https://badge.fury.io/rb/<%= gem_name %>.svg)](https://rubygems.org/gems/<%= gem_name %>) [![Pipeline status](https://gitlab.com/tools4devops/psplugins/<%= plugin_name %>/badges/master/pipeline.svg)](https://gitlab.com/tools4devops/psplugins/<%= gem_name %>/commits/master)
 
 [PowerStencil] is the Swiss-army knife templating workflow for developers and ops.
 
@@ -16,6 +16,9 @@ See [official website][PowerStencil site].
 - [What is a PowerStencil plugin ?](#what-is-a-powerstencil-plugin-)
 - [Using this plugin in your `PowerStencil` projects](#using-this-plugin-in-your-powerstencil-projects)
 - [Goal of this plugin](#goal-of-this-plugin)
+- [Plugin dependencies](#plugin-dependencies)
+    - [Standard gems dependencies](#standard-gems-dependencies)
+    - [Dependency to other plugins](#dependency-to-other-plugins)
 - [Plugin capabilities](#plugin-capabilities)
     - [Config](#config)
     - [Subcommands and options](#subcommands-and-options)
@@ -66,9 +69,22 @@ And then you may see information about the plugin by running:
 * `power_stencil info` in the plugins section.
 * `power_stencil plugin --list -v`
 
-# Goal of this plugin
+# Goal of this plugin
 
-# Plugin capabilities
+# Plugin dependencies
+
+## Standard gems dependencies
+
+Standard dependencies are declared normally in the _gemspec file_. They are automatically installed when installing the plugin with `power_stencil plugin --install`.
+
+## Dependency to other plugins
+
+For development purpose, dependency to other plugins are declared in the _gemspec file_ as _development dependency_. 
+
+But within a project, dependencies have to be added to the `:project_plugins` array in the project configuration file (`.ps_project/versioned-config.yaml`).
+
+
+# Plugin capabilities
 
 This plugin provides the following features:
 
@@ -78,13 +94,12 @@ This plugin provides the following features:
 
 ## Post-build actions
 
-## DSL in templates and in `power_stencil shell`
+## DSL in templates and in `power_stencil shell`
 
 ## Entity types
 
 ## Templates-templates
 
-
 # Contributing
 
 Bug reports and pull requests are welcome on Gitlab at https://gitlab.com/tools4devops/psplugins/<%= plugin_name %>/issues. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.

data/etc/meta_templates/plugin_seed/etc/plugin_capabilities.yaml

@@ -32,3 +32,6 @@
 :templates:
   - etc/templates
 
+# Plugin dependencies to other plugins. Use the plugin name and NOT the plugin
+# gem name (in the case of a gem plugin). Declare as well dependencies to local plugins.
+:dependencies: []

data/etc/meta_templates/plugin_seed/psplugin_{entity}.gemspec

@@ -11,6 +11,8 @@ Gem::Specification.new do |spec|
 
   spec.summary       = %q{<%= plugin_name %> is a plugin for the PowerStencil framework.}
   spec.description   = %q{TODO: Write a longer description or delete this line.}
+  # For official plugins
+  # spec.homepage      = "https://powerstencil.brizone.org/#plugins"
   spec.homepage      = "TODO: Put your gem's website or public repo URL here."
   spec.license       = 'MIT'
 

data/etc/meta_templates/plugin_seed/spec/project_helper.rb

@@ -0,0 +1,50 @@
+module PowerStencilTests
+
+  module Project
+
+    TEMP_DIR_PREFIX = 'PS_TESTS_'
+
+    module ClassMethods
+
+
+      def temporary_project(project_name, with_git_support: false, scope: :all)
+        self.instance_eval do
+          puts scope
+          around(scope) do |execution|
+            Dir.mktmpdir(TEMP_DIR_PREFIX) do |tests_root_dir|
+              tmp_project_path = File.join tests_root_dir, project_name
+              create_project_including_this_plugin tmp_project_path, with_git_support: with_git_support
+              execution.run
+              @tmp_project_path = nil
+            end
+          end
+        end
+      end
+
+      def plugin_path
+        File.expand_path File.join('..', '..'), __FILE__
+      end
+
+    end
+
+    attr_reader :tmp_project_path
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    def create_project_including_this_plugin(project_path, with_git_support: false)
+      cmd = "power_stencil init --project-path '#{project_path}'"
+      cmd << ' --no-git' unless with_git_support
+      `#{cmd}`
+      project_plugin_path = File.join project_path, '.ps_project', 'plugins'
+      `ln -s '#{self.class.plugin_path}' '#{project_plugin_path}'`
+      @tmp_project_path = project_path
+    end
+
+    def temporary_project_cmd(params)
+      "power_stencil #{params} --project-path '#{tmp_project_path}'"
+    end
+
+  end
+end

data/etc/meta_templates/plugin_seed/spec/spec_helper.rb

@@ -1,6 +1,7 @@
-require "bundler/setup"
+require 'bundler/setup'
 require 'power_stencil'
 require "<%= plugin_name %>"
+require 'project_helper'
 
 RSpec.configure do |config|
   # Enable flags like --only-failures and --next-failure

data/etc/meta_templates/plugin_seed/spec/{entity}_spec.rb

@@ -1,10 +1,30 @@
 RSpec.describe <%= plugin_module_name %> do
+
+  include PowerStencilTests::Project
+  temporary_project 'test_project', scope: :all
+
+  let(:plugin_list) { 'plugin --list' }
+  let(:test_entity) { '<%= plugin_name %>_entity/test_<%= plugin_name %>' }
+  let(:create_<%= plugin_name %>) { "create #{test_entity}" }
+  let(:get_<%= plugin_name %>) { "get #{test_entity}" }
+
   it 'has a version number' do
     expect(<%= plugin_module_name %>::VERSION).not_to be nil
   end
 
-  it 'does something useful' do
+  it 'should add a "<%= plugin_name %>" sub-command' do
+    expect(`#{temporary_project_cmd plugin_list}`).to match '- <%= plugin_name %>'
+  end
+
+  it 'should be possible to create a "<%= plugin_name %>_entity"' do
+    `#{temporary_project_cmd create_<%= plugin_name %>}`
+    expect($?.success?).to be_truthy
+    expect(`#{temporary_project_cmd get_<%= plugin_name %>}`).not_to be_empty
+  end
+
+  it 'should do something useful' do
     pending 'Tests implementation'
     RSpec.fail
   end
+
 end

data/etc/power_stencil.yaml

@@ -72,7 +72,9 @@
 # Map to define which kind of template engine for which type of file. Be careful if you
 # overlap two definitions. Warning, it is ruby Regex not shell pattern !
 :templating_engines_map:
-  # Currently all files are rendered using ERB engine
+  # Haml for .haml files
+  :haml: '\.haml$'
+  # All the rest with ERB
   :erb: '.*'
 
 # Files matching particular patterns can be changed on the fly
@@ -82,6 +84,8 @@
   ^(.+)\.zzzgitignore\.erb$: '\1.gitignore'
   # Erb files
   ^(.+)\.erb$: '\1'
+  # Haml files
+  ^(.+)\.haml$: '\1'
 
 
 # PLUGINS
@@ -110,6 +114,7 @@
 :completion_target:
   :zsh:
     :completion_dir: ~/.zsh/completion
+    :project_completion_filename: .zsh_project_completion
 
 
 

data/etc/templates/plugin_definition/.gitignore

@@ -6,6 +6,7 @@
 /pkg/
 /spec/reports/
 /tmp/
-
+/.idea/
+Gemfile.lock
 # rspec failure tracking
 .rspec_status

data/etc/templates/plugin_definition/.gitlab-ci.yml

@@ -0,0 +1,11 @@
+image: "ruby:2.3"
+
+before_script:
+  - gem install bundler --no-document
+  - bundle install --jobs $(nproc)  "${FLAGS[@]}"
+  - git config --global user.email "noone@nowhere.org"
+  - git config --global user.name "Testman"
+
+rspec:
+  script:
+    - bundle exec rspec

data/etc/templates/plugin_definition/README.md

@@ -2,7 +2,7 @@
 <%= plugin_title_name %>
 <%= '=' * plugin_title_name.size %>
 
-[![Gem Version](https://badge.fury.io/rb/<%= gem_name %>.svg)](https://rubygems.org/gems/<%= gem_name %>) [![Pipeline status](https://gitlab.com/tools4devops/psplugins/<%= gem_name %>/badges/master/pipeline.svg)](https://gitlab.com/tools4devops/psplugins/<%= gem_name %>/commits/master)
+[![Gem Version](https://badge.fury.io/rb/<%= gem_name %>.svg)](https://rubygems.org/gems/<%= gem_name %>) [![Pipeline status](https://gitlab.com/tools4devops/psplugins/<%= plugin_name %>/badges/master/pipeline.svg)](https://gitlab.com/tools4devops/psplugins/<%= gem_name %>/commits/master)
 
 [PowerStencil] is the Swiss-army knife templating workflow for developers and ops.
 
@@ -16,6 +16,9 @@ See [official website][PowerStencil site].
 - [What is a PowerStencil plugin ?](#what-is-a-powerstencil-plugin-)
 - [Using this plugin in your `PowerStencil` projects](#using-this-plugin-in-your-powerstencil-projects)
 - [Goal of this plugin](#goal-of-this-plugin)
+- [Plugin dependencies](#plugin-dependencies)
+    - [Standard gems dependencies](#standard-gems-dependencies)
+    - [Dependency to other plugins](#dependency-to-other-plugins)
 - [Plugin capabilities](#plugin-capabilities)
     - [Config](#config)
     - [Subcommands and options](#subcommands-and-options)
@@ -66,9 +69,22 @@ And then you may see information about the plugin by running:
 * `power_stencil info` in the plugins section.
 * `power_stencil plugin --list -v`
 
-# Goal of this plugin
+# Goal of this plugin
 
-# Plugin capabilities
+# Plugin dependencies
+
+## Standard gems dependencies
+
+Standard dependencies are declared normally in the _gemspec file_. They are automatically installed when installing the plugin with `power_stencil plugin --install`.
+
+## Dependency to other plugins
+
+For development purpose, dependency to other plugins are declared in the _gemspec file_ as _development dependency_. 
+
+But within a project, dependencies have to be added to the `:project_plugins` array in the project configuration file (`.ps_project/versioned-config.yaml`).
+
+
+# Plugin capabilities
 
 This plugin provides the following features:
 
@@ -78,13 +94,12 @@ This plugin provides the following features:
 
 ## Post-build actions
 
-## DSL in templates and in `power_stencil shell`
+## DSL in templates and in `power_stencil shell`
 
 ## Entity types
 
 ## Templates-templates
 
-
 # Contributing
 
 Bug reports and pull requests are welcome on Gitlab at https://gitlab.com/tools4devops/psplugins/<%= plugin_name %>/issues. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.