Palimpsest
by Evan Boyd Sosenko.
No web framework, no problem: Palimpsest gives any custom or legacy project a modern workflow and toolset.
Built flexible, simple, and customizable. Palimpsest runs on top of any project and acts as a post processor for your code. Features a Sprockets asset pipeline and easy integration with Kit.
Installation
Add this line to your application's Gemfile:
gem 'palimpsest'
And then execute:
$ bundle
Or install it yourself as:
$ gem install palimpsest
Documentation
The primary documentation for Palimpsest is this README and the YARD source documentation.
YARD documentation for all gem versions is hosted on the Palimpsest gem page. Documentation for the latest commits is hosted on the RubyDoc.info project page.
Usage
Palimpsest should not be considered stable until version 1.0.0 is released.
This README will focus on examples of how to get your project working with Palimpsest through Palimpsest::Environment
.
Palimpsest's classes are independently useful outside of Palimpsest::Environment
, and each is
well documented for that purpose.
The first step is always
require 'palimpsest'
Additional requirements
Some optional Palimpsest features depend on gems not required by Palimpsest itself. Include these in your project's Gemfile if you plan to use them.
For example, to use the image_compression
option, add to your Gemfile
gem 'sprockets-image_compressor'
and to your project
require 'sprockets-image_compressor'
or if you set js_compressor: uglifier
you must add to your Gemfile
gem 'uglifier'
and to your project
require 'uglifier'
Similarly you must include gems for any sprockets engines you want to use.
Creating and populating an environment
Create an environment with
environment = Palimpsest::Environment.new
For most operations you will need to specify a site
which can be any object which
responds to the methods Palimpsest::Environment
assumes exists in some of its own methods.
A model class Palimpsest::Site
is included which implements all possible expected methods.
Finally, the examples below assume default options for each class, but these can be overridden with #options
.
site = Palimpsest::Site.new
site.name = 'my_app'
environment.site = site
To populate the environment from a git repo,
site.repo = Grit::Repo.new '/path/to/project/repo'
environment.treeish = 'my_feature' # if you want something other then 'master'
environment.populate
or to populate from a directory,
site.source = '/path/to/project/source'
environment.populate from :source
Either way you will get a copy of your site in a new random working directory,
environment.directory #=> '/tmp/palimpsest_my_app_6025680'
Working with the environment
If you project contains a file palimpsest_config.yml
,
then its configuration is available with environment.config
.
An example palimpsest_config.yml
.
The configuration file tells Palimpsest how to behave when you ask it to manipulate the environment and acts as a shortcut to working with the other Palimpsest classes directly.
If you made it this far, you can make Palimpsest do all sorts of magic to your code in the working directory.
For example, to search through you code for tags referencing assets, process and save those assets with sprockets, and replace the tags with references to the processed assets,
environment.compile_assets
Check the Palimpsest::Environment
documentation
for all available magic, and freely extend the class to add new magic applicable to your project.
Finishing with the environment
You can copy the current state of the environment to another directory with Palimpsest::Environment#copy
.
By default, this will use site.path
for the destination, or you can specify with
environment.copy dest: '/path/to/out/dir'
To delete the working directory, use
environment.cleanup
Development
Source Repository
The Palimpsest source is hosted at github. To clone the project run
$ git clone [email protected]:razor-x/palimpsest.git
License
Palimpsest is licensed under the MIT license.
Warranty
This software is provided "as is" and without any express or implied warranties, including, without limitation, the implied warranties of merchantibility and fitness for a particular purpose.