power_stencil 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 0553232c716ddf2858efa77a0d9617ca39576d15
+  data.tar.gz: cad65330d8a994849b940c519b008cdb9ba39990
+SHA512:
+  metadata.gz: 84ded250b7f0080a28e8d07a3fddad16b5a5fc4c220bf87f1a0b7591d9b68804f954e70a56b0844d43f924e9b8849457bf16cd4af39eec806080905a68908151
+  data.tar.gz: 0be35290850eb3ada35a95a6278904a430d19d96d3fafc68ba81d3ea0018657bdd7baf95990f5abafffb69967e7244bd87965fb8323d8550446ce3e5c69e4299

data/.gitignore

@@ -0,0 +1,13 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/pkg/
+/spec/reports/
+/tmp/
+/etc/templates/plugin_definition-*.old/
+# rspec failure tracking
+.rspec_status
+/.idea/
+/test/test_project/build/

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,5 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.3.1
+before_install: gem install bundler -v 1.15.1

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at lbnetid+gh@gmail.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in power_stencil.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2018 Laurent B.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,194 @@
+PowerStencil
+============
+
+`Power Stencil` is the Swiss-army knife templating workflow for developers and ops.
+
+<!-- TOC -->
+
+- [Core concepts](#core-concepts)
+- [Pfff, yet another templating engine...](#pfff-yet-another-templating-engine)
+- [Installation](#installation)
+- [Usage](#usage)
+    - [Help](#help)
+    - [Creating a `PowerStencil` project](#creating-a-powerstencil-project)
+    - [`PowerStencil` project structure](#powerstencil-project-structure)
+    - [Getting started](#getting-started)
+- [Contributing](#contributing)
+    - [License](#license)
+    - [Code of Conduct](#code-of-conduct)
+
+<!-- /TOC -->
+
+# Core concepts
+
+`PowerStencil` proposes a radical approach on how to manage your shared configuration.
+
+Internally `PowerStencil` is composed of a data repository and a pretty standard templating flow to generate whatever is needed by your project or organization:
+![simple-flow-image]
+Configuration is one of the most complex things to maintain, and anyone who participated in a large scale piece of software or documentation knows how complex it is to maintain, keep consistent and avoid duplication on the long run across the various projects that may share this configuration.
+
+`PowerStencil` provides **development and operations friendly workflows to fully manage the maintenance of a complex shared config** in order to generate anything you may want like _documentation_, _static sites_, _code_, _configuration_ for multiple tools..., while **avoiding duplication, and manage it like code** !
+
+It is a common pattern to introduce a database to manage this configuration, and it is a very bad idea because it implies extra tooling, and specific developments that de-facto become single point of failure at the heart of your development process. Why would you do that when something as versatile and ubiquitous as Git exists that will __integrate smoothly within your existing development and operations workflows__, builds, CI/CD, while benefiting from all the goodness provided by Git, like branches, decentralization, versioning, tags, code reviews, traceability, simplified fallbacks etc... ?
+
+**With `PowerStencil` everything is maintained in a git repository**: data, templates, specific code. No more config loss, no more change applied without a full lineage.
+
+See some real world [example use cases].
+
+The `PowerStencil` gem provides the `power_stencil` executable which is a pluggable CLI to:
+
+- CRUD [entities] using either an editor or a dedicated REPL
+- Manage [templates]
+- Manage [builds]
+- Create and manipulate [plugins]
+
+# Pfff, yet another templating engine...
+
+**Actually `PowerStencil` is _not_ a templating engine** per se. Instead it uses already existing and proven templating engines.
+Currently it uses [ERB], which is pretty standard in [Ruby] world, but this is not hardcoded and any templating engine could be used (in parallel, meaning different templating engines can be used automatically depending on what you actually want to generate), even if only [ERB] is implemented for the time-being, `PowerStencil` is modular from ground-up and at least a second implementation for [Haml] templating engine is planned to ease generation of XML-like files, still currently you can do it with [ERB]. See the [templates] section for more information about templates in `PowerStencil`.
+
+No, the real value of `PowerStencil` is not really in its templating capabilities even if very powerful, but in the development flow it proposes around this templating mechanism for both development and/or operations teams, in the way you organize and trace the data which is the real asset, and in the way you can easily extend it to fit the particular needs of a project or organization.
+
+# Installation
+
+You need a working install of the [Ruby] language (>= 2.2).
+
+You can install the `PowerStencil` gem by issuing the usual:
+
+    $ gem install power_stencil
+
+# Usage
+
+## Help
+
+The `power_stencil` CLI provides a contextual help. You can start by:
+
+    $ power_stencil --help
+
+That will display a basic help:
+
+```shell
+This is power_stencil. A powerful templating engine.
+-- Options ---------------------------------------------------------------------
+    -v, --verbose  Displays extra runtime information.
+    -h, --help  Displays this help.
+    --program-version, -V, --version  Displays program version.
+    --simulate  Will not perform actual actions
+    --debug  Debug mode
+    --debug-on-err, --debug-on-stderr  Sends debugging to SDTERR
+    --log-level  Defines the level of logging (0 to 5)
+    --log-file  Specifies a file to log into
+    --truncate-log-file  Truncates the log file (appends by default)
+    --project-path  Specifies a startup path to use instead of '.'
+    --auto  Bypasses command-line confirmations to the user
+
+--------------------------------------------------------------------------------
+ Following subcommands exist too:
+ For more information you can always issue sub_command_name --help...
+--------------------------------------------------------------------------------
+ * init: Initializes a PowerStencil repository ...
+ * info: Generic information about the repository ...
+ * new-plugin: Generates the skeleton for a plugin ...
+ * get: Query entities from repository ...
+ * shell: Opens a shell to interact with entities ...
+ * check: Check repository entities consistency ...
+ * create: Creates entities in the repository ...
+ * edit: Edit entities from repository ...
+ * delete: Delete entities from repository ...
+ * build: Builds entities ...
+```
+
+The program uses the standard paradigm of sub-commands (à-la-git), and each can have its own options that you can check using:
+
+    $ power_stencil <subcommand> --help
+
+[Plugins] may bring extra subcommands and/or options, so depending on the project you are working in, the output of `--help` may differ...
+
+## 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 if you want you can specify the directory where you want the project to be created:
+
+    $ power_stencil init --project-path /where/you/want
+
+The `--project-path` option can be applied to any sub-command, but à-la-git, once the project created if you are anywhere within the project tree, you don't need to specify the project path.
+
+## `PowerStencil` project structure
+
+The structure of a brand new `PowerStencil` project is the following:
+
+```
+├── .gitignore
+└── .ps_project
+    ├── entities
+    │   └── README.md
+    ├── entity_definitions
+    │   └── README.md
+    ├── personal-config.yaml
+    ├── plugins
+    ├── templates-templates
+    │   └── README.md
+    ├── user_entities
+    │   └── README.md
+    └── versioned-config.yaml
+```
+New directories will appear once you start some [builds] or when you will define [templates].
+
+Not all the files in this directory should be versioned, and this the reason why there is a preconfigured `.gitignore` at the root of the project.
+
+The project has two distinct config files. Keep the official project config in the `.ps_project/versioned-config.yaml` which, as its name suggest will be versioned. But any developer who wants to temporarily override some configuration should do it in the `.ps_project/personal-config.yaml` which is not be versioned. The content defined in the latter overrides the content of the official one. This is a clean way for anyone who wants to test something to safely do it locally without the risk to pollute the central repo.
+
+There is the same mechanism between `.ps_project/entities` and `.ps_project/user_entities`, but as opposed to the two aforementioned config files you should not edit anything directly there, but instead interact using the CLI. More information on how to manage entities [here][entities].
+
+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. See the [plugins] documentation.
+
+## Getting started
+
+The core of the system is the `entity`, so you should start by having a look at what entities are, how they are easily managed using the `PowerStencil` CLI and shell.
+
+:arrow_forward: [Entities]
+
+Then it is important to understand how to use entities within `templates`. Templates are the way to generate something (doc, code, descriptors, sites, whatever...) from the data that the entities represent.
+
+:arrow_forward: [Templates]
+
+The mechanism that combines entities and templates is called a `build`. A build is always attached to an entity (you build something). The result of a build is a set of files. Optionally an action can be triggered after the files are generated (could be as simple as calling a script that has been generated).
+
+:arrow_forward: [Builds]
+
+`PowerStencil` could stop there, and you would be able to do whatever you want, but there is a whole world beyond. `Plugins` provide a way to completely extend `PowerStencil`, further control relations between entities, implement complex post-build actions, add CLI sub-commands and options. Plugins can be local to the project or coming in the form of standard Ruby Gems ! The icing on the cake...
+
+:arrow_forward: [Plugins]
+
+# Contributing
+
+Bug reports and pull requests are welcome on Gitlab at https://gitlab.com/tools4devops/power_stencil. 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 codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct].
+
+<!-- End of Document -->
+
+<!-- Pages -->
+[templates]: doc/templates.md "Templates in PowerStencil"
+[entities]: doc/entities.md "Entities in PowerStencil"
+[builds]: doc/builds.md "Builds in PowerStencil"
+[plugins]: doc/plugins.md "Plugins in PowerStencil"
+[example use cases]: doc/example_use_cases.md "Example uses cases using PowerStencil"
+[code of conduct]: CODE_OF_CONDUCT.md
+
+<!-- Code links -->
+[ERB implementation]: lib/power_stencil/engine/renderers/erb.rb "Mostly the only module you need to clone to implement another templating engine"
+
+<!-- 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"

data/Rakefile

@@ -0,0 +1,6 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'power_stencil'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require 'irb'
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/bin/update_plugin_template

@@ -0,0 +1,79 @@
+#!/usr/bin/env ruby
+
+
+require 'bundler/setup'
+require 'tmpdir'
+require 'power_stencil'
+
+LOGGER = Logger.new STDERR
+
+def logger
+  LOGGER
+end
+
+include Climatic::Proxy
+include PowerStencil::Utils::FileHelper
+include PowerStencil::Utils::DirectoryProcessor
+
+POWER_STENCIL_ETC = File.expand_path File.join( '..', '..', 'etc'), __FILE__
+POWER_STENCIL_TEMPLATES_PATH = File.join POWER_STENCIL_ETC, 'templates'
+PLUGIN_DEFINITION_PATH = File.join POWER_STENCIL_TEMPLATES_PATH,'plugin_definition'
+PLUGIN_SEED_PATH = File.join POWER_STENCIL_ETC, 'meta_templates', 'plugin_seed'
+BACKUP_PATH = "%s-#{timestamp Time.now}.old" % [PLUGIN_DEFINITION_PATH]
+# puts "Plugin definition path: '#{PLUGIN_DEFINITION_PATH}'", "Backup path:            '#{BACKUP_PATH}'"
+
+def generate_gem(gem_name, dir)
+  Dir.chdir dir do
+    # Let's create a new gem using bundle
+    res = `bundle gem #{gem_name} --no-exe`
+    # Remove useless files from generated gem source
+    logger.debug "#{res}"
+    gem_path = File.join dir, gem_name
+    substituted_path = File.join dir, 'plugin_definition'
+    gitdir = File.join gem_path,'.git'
+    libdir = File.join gem_path,'lib'
+    gemspecfile = File.join gem_path, "#{gem_name}.gemspec"
+    FileUtils.remove_entry_secure gitdir
+    FileUtils.remove_entry_secure libdir
+    FileUtils.remove_entry_secure gemspecfile
+    # Copy files from power_stencil seed files
+    FileUtils.copy_entry PLUGIN_SEED_PATH, gem_path
+    # Perform file names and content substitutions
+    process_directory source: gem_path,
+                      destination: substituted_path do |source_file, potential_target_file|
+      next if File.directory? source_file
+      target_file = potential_target_file.gsub gem_name, '{entity}'
+      logger.info "Processing #{source_file} -> #{target_file}"
+      file_content = File.read source_file
+      file_content.gsub! gem_name, '<%= plugin_module_name %>'
+      modes = File.stat(source_file).mode
+      FileUtils.mkdir_p(File.dirname target_file)
+      File.open(target_file, 'w') do |file|
+        file.puts file_content
+      end
+      logger.debug "Processed #{target_file}"
+    end
+
+  end
+end
+
+def update_definition_template(source_dir, dest_dir)
+  # Backup old plugin template definition in power stencil gem
+  FileUtils.mv PLUGIN_DEFINITION_PATH, BACKUP_PATH
+  # Copy new definition into gem
+  FileUtils.copy_entry source_dir, dest_dir
+end
+
+fake_gem_name = 'XXXXXXXXXXXX'
+
+Dir.mktmpdir do |tmpdir|
+  Dir.chdir tmpdir do
+    generate_gem fake_gem_name, tmpdir
+    generated_gem_path = File.join(tmpdir, 'plugin_definition')
+    update_definition_template generated_gem_path, PLUGIN_DEFINITION_PATH
+    puts 'bye'
+  end
+end
+
+
+

data/doc/builds.md

@@ -0,0 +1,267 @@
+Builds
+======
+
+<!-- TOC -->
+
+- [Overview of the build process](#overview-of-the-build-process)
+- [The "_compilation_" process](#the-_compilation_-process)
+    - [Extending an entity](#extending-an-entity)
+    - [Overriding entities and build scenarii](#overriding-entities-and-build-scenarii)
+- [The "_detemplatization_" process](#the-_detemplatization_-process)
+- [Post-process actions](#post-process-actions)
+
+<!-- /TOC -->
+[:back:][Documentation root]
+
+
+# Overview of the build process
+
+
+You build a [buildable] entity by issuing `power_stencil build <entity_type>/<entity_name>`. If you try to build an entity which is not buildable, the process fail with an error message.
+
+Let's describe a bit more in detail what this build process is:
+
+![entity-build-flow]
+
+Humm :thinking:... What is this _compilation_ step that appears on this schema ??! I thought Ruby was an interpreted language...
+
+I guess you understood this is not a "real" _compilation_ process we are discussing about here, like in the sense of compiling some Java or C code.
+
+# The "_compilation_" process
+
+The mechanism of the compilation is coming from the [universe_compiler] Gem, but the two following features are the ones you really need to understand.
+
+:information_source: The compilation process can be applied to any entity, ie it doesn't need to be [buildable] (see in next paragraph how to run the compilation). But an entity needs to be [buildable] to use `power_stencil build` which corresponds actually to _compilation_ + _detemplatization_.
+
+## Extending an entity
+
+We could describe this mechanism as inheritance at entity level (not entity type !), said differently this a way for an entity to _inherit_ (or _extend_ in the `PowerStencil` paradigm) the content of another entity.
+
+Let's try this with two `base_entities`.
+
+First let's define a root entity to inherit from:
+
+    $ power_stencil create base_entity/root_entity --edit
+
+and set the folloging content:
+
+```yaml
+--- !ruby/object:PowerStencil::SystemEntityDefinitions::ProjectEntity
+:name: root_entity
+:property_root: value in root_entity
+:array_root:
+- value A
+- value B
+:hash_root:
+  item1: value 1
+  item2: value 2
+```
+
+Now let's create a second entity to extend this one:
+
+    $ power_stencil create base_entity/inherited_entity --edit
+
+And define its content as:
+
+```yaml
+--- !ruby/object:PowerStencil::SystemEntityDefinitions::ProjectEntity
+:name: inherited_entity
+:a_specific_property: This one only exists in inherited entity
+:extends: !psref
+  type: :base_entity
+  name: root_entity
+:array_root:
+- value from inherited_entity
+:hash_root:
+  item2: value2 but from inherited
+  item3: value3
+```
+
+Once done, if we do a `power_stencil get base_entity/inherited_entity --raw` this exactly what will get. But `PowerStencil` gives a possibility to see how this entity will look like after the compilation process using the `--compiled` option:
+
+So if you do
+
+    $ power_stencil get base_entity/inherited_entity --raw --compiled
+
+This is what you get:
+
+```yaml
+--- !ruby/object:PowerStencil::SystemEntityDefinitions::ProjectEntity
+:name: inherited_entity
+:a_specific_property: This one only exists in inherited entity
+:property_root: value in root_entity
+:array_root:
+- value from inherited_entity
+:hash_root:
+  item1: value 1
+  item2: value2 but from inherited
+  item3: value3
+:extends: !psref
+  type: :base_entity
+  name: root_entity
+```
+
+You can notice that this second object looks now like a merged entity. Here are the rules of the merge:
+
+- the entity extending another one has always precedence, meaning that if a property is defined in both, only the latter is kept.
+- hashes are treated a bit differently as a real merge of the two hashes is performed (which is not the case of arrays or simple properties).
+- the `extends` property is kept even after compilation for reference (meaning that in a template you can still access values of the entity you are extending).
+
+:warning: **The entity you extend has to be of the same entity type** or the compilation will fail (actually unless you created the entity yaml file manually, the framework won't even let you save it if the entity inheritance is invalid) !
+
+## Overriding entities and build scenarii
+
+You may have noticed from the output of `power_stencil info` that there is a type of entity named `entity_override`. 
+
+This is a very specific type of entity linked to the compilation process.
+
+The goal of this specific entity is to provide a mechanism to override some of the properties of other entities in the scope of a _build scenario_. This is really a feature turned towards testing possibilities, by it for developers or ops, and as such generally `entity_override` are often created as [local entities] (although they really could be created as standard versioned entities).
+
+Let's create our first override:
+
+    $ power_stencil create entity_override/test_override --edit --user-storage
+
+And define its content:
+
+```yaml
+--- !ruby/object:UniverseCompiler::Entity::Override
+:overrides:
+- !psref
+  type: :base_entity
+  name: inherited_entity
+:name: test_override
+:property_from_overide: foo
+:scenario: dev_tests
+:hash_root:
+  item3: overridden value
+```
+:information_source: First thing to notice is that an `entity_override` is **able to override properties of multiples entities at once** ! Hence the fact the `overrides` property is an array.
+
+:information_source: **There is no constraint on the entity types this override applies to** (as opposed to the extend mechanism)
+
+The `scenario` property specifies the build scenario this override will be applied for.
+
+:information_source: You can define as many `entity_overrides` as you want for a specific build scenario.
+
+Ok, then what happens to `base_entity/inherited_entity` ?
+
+As expected, without specifying a build scenario nothing changes
+
+    $ power_stencil get base_entity/inherited_entity --raw --compiled
+
+```yaml
+--- !ruby/object:PowerStencil::SystemEntityDefinitions::ProjectEntity
+:name: inherited_entity
+:property_root: value in root_entity
+:array_root:
+- value from inherited_entity
+:hash_root:
+  item1: value 1
+  item2: value2 but from inherited
+  item3: value3
+:a_specific_property: This one only exists in inherited entity
+:extends: !psref
+  type: :base_entity
+  name: root_entity
+```
+But if you specify the dev_tests scenario:
+
+    $ power_stencil get base_entity/inherited_entity --raw --compiled --scenario dev_tests
+```yaml
+--- !ruby/object:PowerStencil::SystemEntityDefinitions::ProjectEntity
+:name: inherited_entity
+:property_root: value in root_entity
+:array_root:
+- value from inherited_entity
+:hash_root:
+  item1: value 1
+  item2: value2 but from inherited
+  item3: overridden value
+:a_specific_property: This one only exists in inherited entity
+:extends: !psref
+  type: :base_entity
+  name: root_entity
+:property_from_overide: foo
+```
+
+:information_source: You can notice that **the override mechanism occurs after the extend mechanism**, and both can be used on the same entities.
+
+:information_source: The `--scenario` command line option obviously exists as well for the `build` sub-command so that you can run a build in the context of a scenario.
+
+This override mechanism is really a great way for developers or ops to test something while being sure to avoid introducing errors in the entities repository (by "temporarily patching" an entity to perform a test... and then committing it by mistake... smells like real life, doesn't it ?).
+
+
+# The "_detemplatization_" process
+
+Now we have almost everything we need:
+
+- We have a nice traceable mechanism to manage [entities] (our shared data), including [special features to keep them dry](#extending-an-entity) and perform [test scenarii](#overriding-entities-and-build-scenarii).
+- We have a pluggable [templating mechanism][templates], with mechanisms to decide to [which files it may be applied to](#xxx_ignore-files) (or actually which files it should _not_ apply to).
+
+
+When we are using `power_stencil build`, the entities are first compiled then templates associated to the entity specified are used in order to generate the "_detemplatized_" files.
+
+Those generated files are located in a subfolder of the `build` directory of the project (which by default is not versioned as per `.git_ignore` located at the root folder of the project).
+
+The pattern for the name of the folder where the files are generated is the following:
+
+`build/<date_and_time_stamp><entity_type>_<entity_name>/<entity_type>_<entity_name>`
+
+Why is there 2 times entity type and name ?
+
+This is because `power_stencil build` accepts more than one entity as parameter and in this case the first level would be the type and name of all the entities concatenated and then there would be  second level folders, one per per entity.
+
+# Post-process actions
+
+
+By default `PowerStencil` proposes the `simple_exec` entity type which provides the possibility to run any executable after the build completed. By default it will run a script `main.sh` (automatically generated), but this is completely customizable.
+
+When you create a `simple_exec` entity:
+
+    $ power_stencil create simple_exec/example
+
+Actually two entities are created under the hood:
+
+```shell
+$ power_stencil get example --regexp
+---
+PowerStencil::SystemEntityDefinitions::SimpleExec:
+  :type: :simple_exec
+  :fields:
+    :name: example
+    :post_process: !psref
+      type: :process_descriptor
+      name: simple_exec_example.process
+
+---
+PowerStencil::SystemEntityDefinitions::ProcessDescriptor:
+  :type: :process_descriptor
+  :fields:
+    :name: simple_exec_example.process
+    :process: "./main.sh"
+
+```
+It creates a `process_descriptor` entity (which is referenced from the `simple_exec` entity as the `post_process` field). So you can edit this process descriptor and define there whatever executable you want to be called.
+
+This should already cover 95% of everything needed.
+
+If you want to do something more custom after the build process completed, this is where you will have to do a [plugin][plugins].
+
+[:back:][Documentation root]
+<!-- End of Document -->
+
+<!-- Pages -->
+[Documentation root]: ../README.md "Back to documentation root"
+[entities]: entities.md "Entities in PowerStencil"
+[templates]: templates.md "Templates in PowerStencil"
+[plugins]: plugins.md "Plugins in PowerStencil"
+[buildable]: entities.md#buildable--buildable_by "How to make an entity buildable ?"
+[local entities]: entities.md#local-unversioned-entities "Local unversioned entities"
+
+<!-- Code links -->
+
+<!-- Illustrations -->
+[entity-build-flow]: images/power-stencil-entity-build.svg
+
+<!-- External links -->
+[universe_compiler]: https://gitlab.com/tools4devops/universe_compiler "The underlying engine to manage entities and compilation !"