power_stencil 0.8.11 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: df94a3acebefba79cac4230615727310af33352c
-  data.tar.gz: d9c23c0e8b153af072e533d6e170b412e9bcccdd
+  metadata.gz: f8ef665f1ce87e962192d7725c2dbd851759bc00
+  data.tar.gz: 65d6b440a419dddc9a3f0c46c2b7c80db9d78d90
 SHA512:
-  metadata.gz: ef6af6b335756c7120575eba283887e704371a90032ae24c60f12915ddf43cebdb2205eb58c445b36a374d6255c114150bb816576ef3ded5304ef4227198e43c
-  data.tar.gz: 60b5625ba00c9fa20176f584d32b8c405b9dbf41a93b29d1d24b4bf453cd75d133c74b41e3620d1fef80beb6a44009ba8755c3a2dbdcd1834167b3dc42538131
+  metadata.gz: 8e39368e94c8710dba97db574916017d9a30ce45468d5674787daef4f2ad915af8dba03235d60988a2f887a96020f151dabccd160b32baef0d4421a576339284
+  data.tar.gz: 7a7ba9f93020d3d92954ef997d46d5724ff11e79deec6270e1a283009faf00df56762435532aa8762dbad93ea062af4931b21fb76941fa04ec59cc0b141de69d

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/README.md

@@ -0,0 +1,133 @@
+<% gem_name = "psplugin_#{ plugin_name}" -%>
+<%= 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)
+
+[PowerStencil] is the Swiss-army knife templating workflow for developers and ops.
+
+`<%= plugin_title_name %>` is a [PowerStencil] plugin.
+
+See [official website][PowerStencil site].
+
+
+<!-- TOC -->
+
+- [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)
+    - [Post-build actions](#post-build-actions)
+    - [DSL in templates and in `power_stencil shell`](#dsl-in-templates-and-in-power_stencil-shell)
+    - [Entity types](#entity-types)
+    - [Templates-templates](#templates-templates)
+- [Contributing](#contributing)
+    - [License](#license)
+    - [Code of Conduct](#code-of-conduct)
+
+<!-- /TOC -->
+
+# What is a PowerStencil plugin ?
+
+A `PowerStencil` plugin can be used in the context of a `PowerStencil` project and bring extra features to a standard project.
+
+If you don't know what `PowerStencil` is made for, you may read [the documentation][PowerStencil] first.
+
+Features provided by a plugin can be:
+
+* Extra config.
+* Extra subcommands or options added to the `power_stencil` command-line.
+* Extra post-build actions.
+* Extra DSL methods available in templates and in `power_stencil shell`.
+* Extra entity types.
+* Extra templates-templates.
+
+# Using this plugin in your `PowerStencil` projects
+
+To use this plugin within your `PowerStencil` project, you need to:
+
+* be within a `PowerStencil` project :wink:.
+* declare this plugin in the project configuration (from the root of your project in the `.ps_project/versioned-config.yaml` file).
+
+In this yaml configuration file, you just have to add a new entry in the `:project_plugins` array or simply create it if it is not yet existing:
+
+```yaml
+:project_plugins:
+  - <%= gem_name %>
+```
+If this plugin is not already present on your machine, you may have to download it:
+
+    $ power_stencil plugin --install
+
+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
+
+# 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:
+
+## Config
+
+## Subcommands and options
+
+## Post-build actions
+
+## 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.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License].
+
+## Code of Conduct
+
+Everyone interacting in the PowerStencil project’s codebase, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct].
+
+<!-- End of Document -->
+
+<!-- Pages -->
+[code of conduct]: CODE_OF_CONDUCT.md
+
+<!-- Code links -->
+
+<!-- Illustrations -->
+[simple-flow-image]: doc/images/power-stencil-simple-flow.svg
+
+<!-- External links -->
+[MIT License]: http://opensource.org/licenses/MIT "The MIT license"
+[ERB]: https://ruby-doc.org/stdlib-2.6.3/libdoc/erb/rdoc/ERB.html "Quick ERB description"
+[Haml]: http://haml.info/ "The templating engine for XML-like documents"
+[Ruby]: https://www.ruby-lang.org "The powerful Ruby language"
+[Rails]: https://rubyonrails.org/ "The Ruby on Rails framework"
+[PowerStencil site]: https://powerstencil.brizone.org "Official PowerStencil website"
+[PowerStencil]: https://gitlab.com/tools4devops/power_stencil/blob/master/README.md "PowerStencil documentation"
+[PowerStencil plugins]: https://gitlab.com/tools4devops/power_stencil/blob/master/doc/plugins.md "PowerStencil plugins documentation"

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

@@ -12,13 +12,27 @@ 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.}
   spec.homepage      = "TODO: Put your gem's website or public repo URL here."
-  spec.license       = "MIT"
+  spec.license       = 'MIT'
 
-  # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
-  # to allow pushing to a single host or delete this section to allow pushing to any host.
+  # Change this and following metadata if you don't want your plugin to be an "official" PowerStencil plugin.
+  # ie deployed to https://gitlab.com/tools4devops/psplugins
+  source_code_uri = 'https://gitlab.com/tools4devops/psplugins/<%= plugin_name %>'
+
+  # Gem metadata
   if spec.respond_to?(:metadata)
+    # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
+    # to allow pushing to a single host or delete this line to allow pushing to any host.
     spec.metadata['allowed_push_host'] = "TODO: Set to 'http://mygemserver.com'"
-    # This metadata is mandatory for PowerStencil !!
+
+    # Nice link to your home page on rubygems.org
+    spec.metadata['homepage_uri'] = spec.homepage
+
+    # You have to probably change this if you don't deploy to gitlab
+    spec.metadata['bug_tracker_uri'] = "#{source_code_uri}/issues"
+    spec.metadata['documentation_uri'] = "#{source_code_uri}/blob/master/README.md"
+    spec.metadata['source_code_uri'] = source_code_uri
+
+    # This metadata is mandatory for a PowerStencil plugin !!
     spec.metadata['plugin_name'] = '<%= plugin_name %>'
   else
     raise 'RubyGems 2.0 or newer is required to protect against public gem pushes and PowerStencil plugin mechanism !'
@@ -31,8 +45,9 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.add_development_dependency 'bundler', '~> 2.0.2'
+  spec.add_development_dependency 'bundler'
   spec.add_development_dependency 'rake', '~> 10.0'
   spec.add_development_dependency 'rspec', '~> 3.0'
   spec.add_development_dependency 'power_stencil', "~> <%= PowerStencil::VERSION %>"
+
 end

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

@@ -0,0 +1,16 @@
+require 'bundler/setup'
+require 'power_stencil'
+require "<%= plugin_name %>"
+require 'project_helper'
+
+RSpec.configure do |config|
+  # Enable flags like --only-failures and --next-failure
+  config.example_status_persistence_file_path = ".rspec_status"
+
+  # Disable RSpec exposing methods globally on `Module` and `main`
+  config.disable_monkey_patching!
+
+  config.expect_with :rspec do |c|
+    c.syntax = :expect
+  end
+end

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

@@ -0,0 +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 '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