documentator 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1cb2b60a388b55a2ef800f92c0727205a2a87593
-  data.tar.gz: 394c3267f4522ac5e9f3b46b8e29cac433d4dc12
+  metadata.gz: 904490606b2d529b0be6d6eae6dab86bc616135b
+  data.tar.gz: eb839473523c14b243ac521f109dcae44da0a2cf
 SHA512:
-  metadata.gz: 2f04a465bf81908689d13b5c3492d0a0a007c8ddbf81e4eaa11ff57cb60c2208707e52c8c875f414ea68279319c292f9cba0b14d257c8a05003345d0807a084a
-  data.tar.gz: ae4e8b7aa668ddc5b5239cc9d76007c19eb7310fc4511807a71ad3f2c71fc9f2d53e261b301fe62a2ecca14b7548295388aa8cdb4143ee14a1ea3075c9b087b1
+  metadata.gz: f37a2c94807676a41a8bba2af9961803ee116389f35cf522b3e7c8ec5934a43df62d111994160926e7e6938be2f44da0b530e82e42d5f70860703f6389711c91
+  data.tar.gz: 9a39379069e0ea1dc7de17bb58b8c31021b94ab37bb84c42b281409e0678dbe982821236c6b821bf93271bdce8025d6824ec777be13dc36eb9c3f511a117e05b

data/lib/documentator.rb

@@ -16,15 +16,19 @@ module Documentator
     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
+    def import(*templates)
+      templates.each do |template|
+        begin
+          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
       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"

data/lib/documentator/templates/elasticsearch.md

@@ -0,0 +1,239 @@
+# Elasticsearch
+
+
+[Elasticsearch](http://www.elasticsearch.org/) est un moteur de recherche
+distribué basé sur Lucene qui offre une API JSON RESTful et une quantité assez
+impressionnante d'options de recherches. Il est très simple à mettre en place
+et s'est imposé chez nous comme la solution de référence dès que nous avons une
+recherche un peu évoluée à mettre en place.
+
+## Installation
+
+
+### Pour une installation en local
+
+Le plus simple pour une installation en local est d'utiliser [Desi](https://github.com/AF83/desi) :
+
+```shell
+gem install desi && desi install
+```
+
+Par défaut, Desi installera ES dans le répertoire `$HOME/elasticsearch`, mais
+on peut facilement [changer ce paramètre](https://github.com/AF83/desi#change-settings).
+
+Une fois ES installé par Desi, on peut très simplement à la fois le lancer et
+afficher les logs en faisant `desi start --tail`. Pour arrêter le démon, faire
+`desi stop`, tout simplement. Pour les autres options proposées par Desi,
+référez-vous à [la page du projet](https://github.com/AF83/desi).
+
+Par défaut, Elasticsearch tournera sur le port 9200 de _localhost_.
+
+### Installation sur un serveur
+
+Le plus simple est de récupérer l'archive deb
+[directement depuis la page _download_ du projet](http://www.elasticsearch.org/download/).
+
+L'installation est là aussi très simple. On peut se référer à [la page
+correspondante sur le site du projet](http://www.elasticsearch.org/guide/reference/setup/installation.html)
+pour plus de détails.
+
+### Gotcha
+
+Bien que des optimisations aient été apportées pour diminuer sa gourmandise en
+la matière, ES fait une consommation importante de descripteurs de fichiers.
+Les réglages par défaut du nombre maximum de descripteurs de fichiers autorisés
+par utilisateur sur un système Linux sont généralement rapidement atteints,
+avec comme conséquence le message d'erreur `Too many open files`.
+
+Pour prévenir ce problème, il convient donc d'augmenter cette limite pour
+l'utilisateur qui lancera le démon Elasticsearch. La documentation du projet
+recommande de le hausser à 32 000, voir 64 000. Sur un système Linux, il
+faudra modifier le fichier `/etc/security/limits.conf`. Cela donne par exemple
+chez moi :
+
+```
+drr  soft  nofile    8192
+drr  hard  nofile    65536
+```
+
+## Plugins
+
+Il existe [un grand nombre de plugins](http://www.elasticsearch.org/guide/reference/modules/plugins.html)
+parmi lesquels quelques-uns peuvent être utiles pour l'administration au
+quotidien :
+
+* [elasticsearch-head](https://github.com/mobz/elasticsearch-head)
+* [elasticsearch-inquisitor](https://github.com/polyfractal/elasticsearch-inquisitor)
+* [bigdesk](https://github.com/lukas-vlcek/bigdesk)
+* [paramedic](https://github.com/karmi/elasticsearch-paramedic)
+
+Pour installer un plugin, il faut aller dans le répertoire où est installé ES
+et lancer la commande `bin/plugin install github_user/github_repo`. Par
+exemple, pour installer les plugins mentionnés ci-dessus avec une installation
+typique faite par Desi, on peut faire :
+
+```shell
+$ cd ~/elasticsearch/current
+$ bin/plugin install mobz/elasticsearch-head
+$ bin/plugin install polyfractal/elasticsearch-inquisitor
+$ bin/plugin install lukas-vlcek/bigdesk
+$ bin/plugin install karmi/elasticsearch-paramedic
+```
+
+Ces plugins seront accessibles sur les URLs suivantes :
+
+* http://localhost:9200/_plugin/head/
+* http://localhost:9200/_plugin/inquisitor/
+* http://localhost:9200/_plugin/bigdesk/
+* http://localhost:9200/_plugin/paramedic/
+
+
+
+## Bonnes pratiques
+
+
+### Se méfier des erreurs de mapping
+
+Les erreurs de
+[mapping](http://www.elasticsearch.org/guide/reference/mapping/index.html) sont
+particulièrement pernicieuses et constituent d'expérience la plus grosse source
+de fragilité. Il s'agit d'ailleurs en premier lieu de problèmes posés par
+Lucene et non par ES proprement dit.
+
+Elles se manifestent par l'impossibilité d'indexer un document dont la
+structure ne correspond pas à celle attendue par l'index où on veut le stocker.
+Cela peut avoir des conséquences particulièrement gênantes en production car
+la suppression/recréation de l'index suivie d'une réindexation sera fréquemment
+la seule solution.
+
+Pour s'en prémunir, il convient donc en premier lieu :
+
+1. de ne pas se fier uniquement au [mapping
+    dynamique](http://www.elasticsearch.org/guide/reference/mapping/dynamic-mapping.html)
+   d'Elasticsearch mais d'indiquer explicitement à ES les champs à indexer
+
+2. d'indexer le moins de champs possibles.
+
+  On n'est en effet pas obligé d'*indexer* un champ pour le stocker dans
+  Elasticsearch. On peut tout à fait le stocker dans la
+  [source](http://www.elasticsearch.org/guide/reference/mapping/source-field.html)
+  du document sans qu'il soit pris en compte dans la requête. Elasticsearch
+  — et plus précisément Lucene — le stockera sans chercher à procéder à quelque
+  analyse que ce soit et pourra le restituer tel qu'il lui a été fourni.
+
+  Le mieux est donc d'utiliser les [dynamic\_templates](http://www.elasticsearch.org/guide/reference/mapping/root-object-type.html) pour passer par défaut tous les champs en `"index": "no"`, pour
+  ensuite indexer explicitement les champs désirés au cas par cas.
+
+  Outre la fiabilité accrue, cela réduira également la taille des indexes
+  Lucene et donc la charge du système.
+
+
+Au delà de cette première mesure, il faut également bien sûr mentionner deux
+conseils de bon sens :
+
+  * Tâcher autant que faire se peut de déterminer le plus précisément
+    possible la structure du document et de s'y tenir
+  * Ne pas changer en cours de route la nature d'un champ en conservant son
+    nom à l'identique. On peut changer la cardinalité d'un élement sans
+    changer le mapping, mais son type doit demeurer identique.
+
+
+### Ne pas nommer à l'identique deux champs de natures différentes stockés dans un même index ES
+
+On peut stocker dans un même [index](http://www.elasticsearch.org/guide/reference/glossary/#index)
+Elasticsearch plusieurs [types](http://www.elasticsearch.org/guide/reference/glossary/#type)
+de documents. Il faut cependant garder à l'esprit que tous les documents d'un
+index ES, quel que soit leur type, seront stockés dans le même index Lucene.
+Une des conséquences est qu'on ne peut avoir en parallèle de champs dont le
+nom soit identique d'un type à l'autre mais dont la nature soit différente.
+
+
+### Utiliser les multi-fields pour préparer ses recherches
+
+Les [multi fields](http://www.elasticsearch.org/guide/reference/mapping/multi-field-type.html)
+permettent de spécifier à ES qu'on veut qu'un même champ soit indexé de
+plusieurs façons à la fois. On pourra dès lors faire des requêtes dessus en
+utilisant la syntaxe `nom_du_champ.nom_du_sous_champ`. On peut donc avoir
+plusieurs sous-champs optimisés chacun pour des cas précis : recherche
+_full-text_ normale, tri ou facette, auto-complétion, etc.
+
+
+### Utiliser un champ non "tokenisé" pour effectuer des tris ou des facettes
+
+Afin d'effectuer une recherche _full-text_ sur un champ de type chaîne de
+caractères, il est nécessaire de lui appliquer tout un certain nombre
+d'opérations (typiquement : segmentation en mots, suppression des caractères diacritiques, des
+accents, lemmatisation, etc.) Cependant, ces opérations empêcheront d'effectuer
+certaines opérations qui n'ont de sens qu'appliquées sur le contenu exact du
+champ d'origine, notamment :
+
+* le tri (cela n'a pas de sens de faire un tri sur un champ texte segmenté en
+plusieurs mots différents)
+* les facettes
+
+Pour ces deux cas, il conviendra donc donc soit de définir le _mapping_ du champ
+comme `not_analyzed`, soit d'utiliser le _mapping_ `keyword`. Dans le deux cas,
+il sera indexé tel quel sans segmentation ou modification d'aucune sorte.
+
+Comme indiqué ci-dessus, on peut bien sûr utiliser un *multi-field* si on veut
+indexer le même champ de plusieurs façons à la fois.
+
+### Utiliser l'endpoint `analyze` pour vérifier la façon dont un texte est segmenté
+
+Pour plus de détails, se référer [à la documentation](http://www.elasticsearch.org/guide/reference/api/admin-indices-analyze.html)
+
+### Se méfier des limitations de Tire
+
+[Tire](https://github.com/karmi/tire) est sans conteste la gem Ruby destinée
+à faciliter l'utilisation d'Elasticsearch la plus évoluée. Son développeur
+principal, karmi, a d'ailleurs rejoint récemment l'équipe
+d'[Elasticsearch.com](http://www.elasticsearch.com/), la société qui est
+derrière le projet. Elle est cependant loin d'être exempte de défauts. Elle
+rend les choses simples triviales mais les cas de figure plus complexes peuvent
+devenir rapidement compliqués à mettre en place.
+
+Ses principales limitations :
+
+  * Son DSL de recherche entraîne assez rapidement des confusions entre sa
+    syntaxe propre et celle — foisonnante — d'Elasticsearch.
+
+  * Il est dans l'ensemble très orienté vers un pattern de type Active Record,
+    avec une classe de persistence couplée dans une relation 1-1 avec un index
+    ES. On peut cependant avoir facilement des besoins qui vont au-delà de ce
+    cas de figure
+
+  * une documentation mine de rien lacunaire quand on commence à vouloir avoir
+    des besoins un peu précis.
+
+La gem [stretcher](https://github.com/PoseBiz/stretcher) est née récemment en
+réaction à nombre de ces points. C'est une alternative récente à étudier.
+
+Sinon, il peut être tout aussi intéressant de se faire soi-même un client
+Elasticsearch. (Pour de meilleurs performances, ne pas oublier d'utiliser une
+connexion HTTP persistante.)
+
+## Outils
+
+
+### Librairies
+
+* Ruby: [desi](https://github.com/AF83/desi), [tire](https://github.com/karmi/tire),
+  [stretcher](https://github.com/PoseBiz/stretcher)
+
+* Javascript : [elastic.js](https://github.com/fullscale/elastic.js)
+
+
+### Outils en ligne de commande
+
+* [desi](https://github.com/AF83/desi)
+* [elasticshell](https://github.com/javanna/elasticshell)
+
+
+### Plugins Elasticsearch
+
+* [elasticsearch-head](https://github.com/mobz/elasticsearch-head)
+* [elasticsearch-inquisitor](https://github.com/polyfractal/elasticsearch-inquisitor)
+* [bigdesk](https://github.com/lukas-vlcek/bigdesk)
+* [paramedic](https://github.com/karmi/elasticsearch-paramedic)
+
+(Voir plus haut pour plus de détails.)

data/lib/documentator/templates/mongodb.md

@@ -0,0 +1,74 @@
+# MongoDB
+
+[MongoDB (from "humongous") is a scalable, high-performance, open source NoSQL database.](http://www.mongodb.org/)
+
+## Installation
+
+### Debian
+
+En tant que root:
+
+```
+aptitude install mongodb
+```
+
+Pour une version plus récente, on peut également utiliser [le dépôt de
+10gen](http://docs.mongodb.org/manual/tutorial/install-mongodb-on-debian/).
+
+### Mac OS X
+
+```
+brew install mongodb
+```
+
+## Configuration
+
+Par défaut `mongod` active la journalisation à partir de la v2.0.
+Cela prend beaucoup d'espace disque et est inutile dans un environnement
+de développement. Pour la désactiver, ajouter `nojournal = true`
+dans `/etc/mongod.conf` ou l'option ` --nojournal` en ligne de commande.
+
+```
+# Disables write-ahead journaling
+nojournal = true
+```
+
+## Utilisation
+
+### Shell mongo
+
+Se connecter à la base `myproject_dev` :
+
+```
+mongo --port 27017 --host localhost myproject_dev
+```
+
+### Commandes shell
+
+Quelques exemples sur la collection `foo` :
+
+
+    db.help()                               Toutes les méthodes de mongodb
+    db.foo.help()                           Toutes les méthodes de la collection
+    db.foo.find().help()                    Toutes les méthodes de la méthode find()
+    db.foo.find()                           Liste des documents de la collection
+    db.foo.save({a: 1})                     Enregistre un document dans la collection
+    db.foo.update({a: 1}, { $set:{a: 2} })  Update un document quand a == 1
+    db.foo.find({a: 1})                     Liste des documents de la collection quand a == 1
+
+### Exporter une base
+
+Exporter ma base de donnée `myproject_dev`.
+
+```
+mongodump --db myproject_dev
+```
+
+### Restorer une base
+
+Restorer ma base de donnée `myproject_dev` dans la base `myproject_staging`.
+
+```
+mongorestore --db myproject_staging dump/myproject_dev/
+```
+

data/lib/documentator/templates/neo4j.md

@@ -0,0 +1,35 @@
+# Neo4j
+
+[The Market Leader Property Graph Database](http://www.neo4j.org/)
+
+Une base de données graphe est un système de stockage supportant 
+la persistance des données sous forme de graphe (noeuds, relations) nativement. 
+
+## Installation
+
+Version recommandé stable en édition 'community': 1.8.2
+
+* Debian
+
+``` shell
+# start root shell
+sudo -s
+# Import our signing key
+wget -O - http://debian.neo4j.org/neotechnology.gpg.key | apt-key add - 
+# Create an Apt sources.list file
+echo 'deb http://debian.neo4j.org/repo stable/' > /etc/apt/sources.list.d/neo4j.list
+# Find out about the files in our repository
+apt-get update
+# Install Neo4j, community edition
+apt-get install neo4j
+# start neo4j server, available at http://localhost:7474 of the target machine
+neo4j start
+```
+
+* OSX
+via Homebrew
+``` shell
+brew update && brew install neo4j
+neo4j start
+```
+

data/lib/documentator/version.rb

@@ -1,3 +1,4 @@
+# encoding: utf-8
 module Documentator
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: documentator
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - chatgris
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-03-14 00:00:00.000000000 Z
+date: 2013-03-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: boson
@@ -38,15 +38,18 @@ files:
 - README.md
 - bin/documentator
 - lib/documentator.rb
-- lib/documentator/bootstrap/Archi.ditaa
-- lib/documentator/bootstrap/Archi.md
+- lib/documentator/bootstrap/Architecture.ditaa
+- lib/documentator/bootstrap/Architecture.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/elasticsearch.md
 - lib/documentator/templates/grunt.md
+- lib/documentator/templates/mongodb.md
+- lib/documentator/templates/neo4j.md
 - lib/documentator/templates/nginx.md
 - lib/documentator/templates/ruby.md
 - lib/documentator/version.rb