documentator 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 1cb2b60a388b55a2ef800f92c0727205a2a87593
+  data.tar.gz: 394c3267f4522ac5e9f3b46b8e29cac433d4dc12
+SHA512:
+  metadata.gz: 2f04a465bf81908689d13b5c3492d0a0a007c8ddbf81e4eaa11ff57cb60c2208707e52c8c875f414ea68279319c292f9cba0b14d257c8a05003345d0807a084a
+  data.tar.gz: ae4e8b7aa668ddc5b5239cc9d76007c19eb7310fc4511807a71ad3f2c71fc9f2d53e261b301fe62a2ecca14b7548295388aa8cdb4143ee14a1ea3075c9b087b1

data/LICENSE

@@ -0,0 +1,21 @@
+MIT LICENSE
+
+Copyright (c)  chatgris <jboyer@af83.com>
+
+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,72 @@
+# documentator
+
+documentator has one primary goal: having better docs on our projects.
+
+documentator provides two main features to achieve that goal:
+
+
+### Bootstrap
+
+`bootstrap` provides a minimal set of documentation's file.
+Those are empty, and they *must* be written for each project. This is specific
+to each project:
+
+  * What's the architecture (providing a [ditaa](http://ditaa.sourceforge.net/)
+  schema will make you earns some karma points)?
+  * Dependencies?
+  * Environnements?
+
+
+As a treat, `bootstrap` generates a Gemfile in `project/doc` which include
+[Guide'em up](https://github.com/nono/guide-em-up). Guide'em up can be used to
+preview markdown file in a browser.
+
+### Import
+
+`import` provides some templates of common documentation that should be the same
+from one project to another. And yet, we write them on each project. I mean,
+installing ElasticSearch is always the same.
+
+## Installation
+
+With bundler, add it to your `Gemfile`:
+
+``` ruby
+group :development do
+  gem "documentator", git: "git@github.com:AF83/documentator.git"
+end
+```
+
+## Usage
+
+Commands should be used from the root directory of the current project.
+
+### Bootstrap
+
+``` bash
+bundle exec documentator bootstrap
+```
+
+### Importing templates
+
+``` bash
+bundle exec documentator list
+```
+
+``` bash
+bundle exec documentator import nginx
+```
+
+## Contribution
+
+YES. We want contributions.
+
+* Adding a bootstrap's file is done by adding a file to
+`lib/documentator/bootstrap`.
+* Adding a templates's file is done by adding a file to
+`lib/documentator/templates`.
+
+
+## Copyright
+
+MIT. See LICENSE for further details.

data/bin/documentator

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+
+#require 'documentator'
+require_relative '../lib/documentator'
+
+Documentator::Runner.start

data/lib/documentator.rb

@@ -0,0 +1,55 @@
+# encoding: utf-8
+require 'boson/runner'
+require 'pathname'
+require 'fileutils'
+
+module Documentator
+  class Runner < Boson::Runner
+    include FileUtils
+
+    desc "Generate and populate a doc directory"
+    def bootstrap
+      create_default_dir!
+      Dir[bootstrap_path.join("*")].each do |file|
+        cp(file, doc_path).tap { puts "✓ #{File.basename(file, File.extname(file))} created!" }
+      end
+    end
+
+    desc "import a template to doc directory"
+    def import(template)
+      unless File.exists?(doc_path)
+        puts "You should run `bootstrap` before trying to import documentation"
+        exit 1
+      end
+      cp(templates_path.join("#{template}.md"), doc_path)
+      puts "✓ File #{template} copied."
+    rescue Errno::ENOENT
+      puts "x File #{template} not found."
+    end
+
+    desc "List all templates"
+    def list
+      Dir[templates_path.join("*")].each do |file|
+        puts "* #{File.basename(file, File.extname(file))}"
+      end
+    end
+
+    private
+
+    def create_default_dir!
+      mkdir doc_path rescue nil
+    end
+
+    def doc_path
+      Pathname.new(Dir.pwd).join('doc')
+    end
+
+    def bootstrap_path
+      Pathname.new(File.expand_path("../", __FILE__)).join "documentator", "bootstrap"
+    end
+
+    def templates_path
+      Pathname.new(File.expand_path("../", __FILE__)).join "documentator", "templates"
+    end
+  end
+end

data/lib/documentator/bootstrap/Gemfile

@@ -0,0 +1,4 @@
+# encoding: utf-8
+source :rubygems
+
+gem "guide-em-up"

data/lib/documentator/templates/beanstalkd.md

@@ -0,0 +1,29 @@
+# Beanstalkd
+
+[A simple, fast work queue](http://kr.github.com/beanstalkd/).
+
+## Installation
+
+En tant que root:
+
+``` shell
+aptitude install beanstalkd
+```
+
+## Configuration
+
+Exemple de fichier de configuration:
+
+    ## Defaults for the beanstalkd init script, /etc/init.d/beanstalkd on
+    ## Debian systems. Append ``-b /var/lib/beanstalkd'' for persistent
+    ## storage.
+    BEANSTALKD_LISTEN_ADDR=0.0.0.0
+    BEANSTALKD_LISTEN_PORT=11300
+    DAEMON_OPTS="-l $BEANSTALKD_LISTEN_ADDR -p $BEANSTALKD_LISTEN_PORT"
+
+    ## Uncomment to enable startup during boot.
+    START=yes
+
+`beanstalkd` accepte le flag `-b` suivit d'un chemin. Cette option active un
+binlog. Cela permet de ne pas perdre de message lors d'un redémarrage de
+beanstalkd.

data/lib/documentator/templates/capistrano.md

@@ -0,0 +1,91 @@
+Déploiement avec capistrano
+---------------------------
+
+Pour nos applications, nous mettons en place un script de déploiement
+automatisé. Celui-ci s'appuie sur l'outil Capistrano et nos recettes maison :
+[capistrano-af83](https://github.com/AF83/capistrano-af83).
+
+Sur le serveur
+--------------
+
+Nous conseillons de faire tourner l'application avec un user UNIX au nom du
+projet. Pour ce guide de déploiement, nous supposons que son `$HOME` est
+`/var/www/projet` et que les dépendances (Git, Ruby, Nginx, etc.) ont déjà été
+installées.
+
+Il est alors nécessaire de créer une clé ssh pour cet utilisateur, à l'aide de
+la commande `ssh-keygen`. Puis, il faudra nous fournir cette clé pour que l'on
+ajoute cette clé SSH comme clé de déploiement sur github.
+
+On peut alors se connecter en ssh pour, d'une part, vérifier que ça marche et,
+d'autre part, définir quelques variables d'environnement. Nous avons pour
+habitude de les placer dans le fichier `~/ruby-env` et d'ajouter la ligne
+`source ~/ruby-env` au début du fichier `~/.bashrc`. Voici le contenu de ce
+fichier `ruby-env` :
+
+```
+#!/bin/sh
+export GEM_HOME=~/gem
+export PATH=~/bin:$GEM_HOME/bin:$PATH
+export APP_ROOT=~/prod/current
+export THIN_CONF=~/prod/shared/thin.yml
+
+if [ -z "en_US.UTF-8" ]; then
+  export LANG=en_US.UTF-8
+fi
+
+export RAILS_ENV=production
+
+reload() {
+    pushd $APP_ROOT && bundle exec thin restart -C $THIN_CONF
+    popd
+}
+
+stop() {
+    pushd $APP_ROOT && bundle exec thin stop -C $THIN_CONF
+    popd
+}
+```
+
+Dernière étape coté serveur, il faut installer bundler avec `gem install
+bundler`.
+
+
+Sur la sandbox de déploiement
+-----------------------------
+
+D'autre part, la personne qui fera le déploiement du code a également besoin
+d'accéder à notre dépôt github (envoyez-nous la liste des comptes github) et à
+un environnement Ruby depuis lequel le déploiement capistrano se fera. Sur cet
+environnement, il faudra également installer la gem Ruby bundler (`gem install
+bundler`).
+
+Comme pour le coté serveur, il peut être utile de définir les variables
+d'environnement suivantes si Ruby a été installé en root :
+
+```
+export GEM_HOME=~/gem
+export PATH=~/bin:$GEM_HOME/bin:$PATH
+```
+
+Le déploiement se fera depuis le répertoire contenant le code :
+
+```
+git clone git@github.com:AF83/projet.git
+cd projet
+```
+
+La configuration spécifique pour l'environnement de production peut être
+adaptée dans le fichier `config/deploy/prod.rb` (créez le fichier s'il
+n'existe pas). Les principales variables peuvent être affichées avec `cap prod
+info`.
+
+Lors du premier déploiement, il convient de lancer `cap prod deploy:setup`.
+Puis, chaque déploiement se fera en lançant `cap prod deploy`.
+
+**Note** : il est recommandé de faire un git clone depuis le serveur avant le
+premier déploiement pour éviter le message d'avertissement de ssh (connexion à
+un hôte inconnu).
+
+**Astuce** : il est possible de se connecter en ssh sur le serveur en faisant
+`cap prod ssh`.

data/lib/documentator/templates/grunt.md

@@ -0,0 +1,34 @@
+# Grunt
+
+[The JavaScript Task Runner](http://gruntjs.com/)
+
+## Installation
+
+Version recommandé: 0.4
+Il est supposé que nodejs est installé dans une version supérieure à 0.8
+
+``` shell
+npm install -g grunt-cli
+```
+
+## Modules projet
+
+Pour installer les modules nécessaires au build d'un projet
+
+``` shell
+npm install .
+```
+
+## Utilisation
+
+Pour connaitre la liste des taches disponibles
+
+``` shell
+grunt --help
+```
+
+Dans la plupart des cas, la tache par défaut permet de construire le projet
+
+``` shell
+grunt
+```

data/lib/documentator/templates/ruby.md

@@ -0,0 +1,59 @@
+# Ruby
+
+## Install
+
+Our recommandation is to use the most recent Ruby 1.9.3.
+
+Debian doesn't provide official packages for Ruby 1.9.3, but it's possible to
+use other sources for that. We trust Bearstech and use their debian packages.
+You can use them for Ruby by creating a
+`/etc/apt/sources.list.d/bearstech-ruby1.9.3.list` file with this line:
+
+```
+deb http://deb.bearstech.com/squeeze ruby-1.9.3/
+```
+
+Then, as root, you can launch the install with:
+
+``` shell
+aptitude update && aptitude install ruby1.9.3 ruby1.9.1-dev build-essential libxml2-dev libxslt1-dev libcurl4-gnutls-dev
+```
+
+
+## Configuration
+
+First of all, you need to do some manual setup on the server, create a ruby-env
+shell script with:
+
+``` shell
+cat > ~/ruby-env << EOF
+#!/bin/sh
+export GEM_HOME=~/gem
+export PATH=~/bin:\$GEM_HOME/bin:\$PATH
+if [ -z "\$LANG" ]; then
+  export LANG=en_US.UTF-8
+fi
+export RAILS_ENV=production
+export RACK_ENV=production
+EOF
+```
+
+A gemrc file:
+
+``` shell
+cat > ~/.gemrc << EOF
+gem: --no-ri --no-rdoc
+EOF
+```
+
+And source the ~/ruby-env file on top of bashrc.
+
+
+## Gems
+
+To manage our gems, we use a tool called Bundler. So, you can install them
+by going in the application directory and taping this one-liner:
+
+``` shell
+gem install bundler && bundle install
+```

data/lib/documentator/version.rb

@@ -0,0 +1,3 @@
+module Documentator
+  VERSION = "0.0.1"
+end

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification
+name: documentator
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- chatgris
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-03-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: boson
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: |-
+  documentator provides templates of documentations and
+    command-line utilities to add them to a project.
+email:
+- julien.boyer@af83.com
+executables:
+- documentator
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- bin/documentator
+- lib/documentator.rb
+- lib/documentator/bootstrap/Archi.ditaa
+- lib/documentator/bootstrap/Archi.md
+- lib/documentator/bootstrap/Dependencies.md
+- lib/documentator/bootstrap/Deploy.md
+- lib/documentator/bootstrap/Environments.md
+- lib/documentator/bootstrap/Gemfile
+- lib/documentator/templates/beanstalkd.md
+- lib/documentator/templates/capistrano.md
+- lib/documentator/templates/grunt.md
+- lib/documentator/templates/nginx.md
+- lib/documentator/templates/ruby.md
+- lib/documentator/version.rb
+homepage: https://github.com/AF83/documentator
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.0
+signing_key: 
+specification_version: 4
+summary: Documents all the things
+test_files: []