Merge pull request cakephp#3536 from cakephp/3.0-autocompletion

Improve autocompletion setup instructions
syjust · Jan 9, 2016 · de22544 · de22544
2 parents 39202df + 2ff6ed2
commit de22544
Show file tree

Hide file tree

Showing 2 changed files with 149 additions and 16 deletions.
diff --git a/en/console-and-shells/completion-shell.rst b/en/console-and-shells/completion-shell.rst
@@ -54,14 +54,42 @@ For example::
 
 Returns::
 
-    --help -h --verbose -v --quiet -q --connection -c --template -t
+    --help -h --verbose -v --quiet -q --everything --connection -c --force -f --plugin -p --prefix --theme -t
 
-Bash Example
-============
+You can also pass an additional argument being the shell sub-command : it will
+output the specific options of this sub-command.
+
+How to enable Bash autocompletion for the CakePHP Console
+=========================================================
+
+First, make sure the **bash-completion** library is installed. If not, you do it
+with the following command::
+
+    apt-get install bash-completion
+
+Create a file named **cake** in **/etc/bash_completion.d/** and put the
+:ref:`bash-completion-file-content` inside it.
+
+Save the file, then restart your console.
+
+.. note::
 
-The following bash example comes from the original author::
+    If you are using MacOS X, you can install the **bash-completion** library
+    using **homebrew** with the command ``brew install bash-completion``.
+    The target directory for the **cake** file will be
+    **/usr/local/etc/bash_completion.d/**.
 
-    # bash completion for CakePHP console
+.. _bash-completion-file-content:
+
+Bash Completion file content
+----------------------------
+
+This is the code you need to put inside the **cake** file in the correct location
+in order to get autocompletion when using the CakePHP console::
+
+    #
+    # Bash completion file for CakePHP console
+    #
 
     _cake()
     {
@@ -94,20 +122,58 @@ The following bash example comes from the original author::
             opts=$(${cake} Completion subcommands $prev)
             COMPREPLY=( $(compgen -W "${opts}" -- ${cur}) )
             if [[ $COMPREPLY = "" ]] ; then
-                COMPREPLY=( $(compgen -df -- ${cur}) )
+                _filedir
                 return 0
             fi
             return 0
         fi
 
-
         opts=$(${cake} Completion fuzzy "${COMP_WORDS[@]:1}")
         COMPREPLY=( $(compgen -W "${opts}" -- ${cur}) )
         if [[ $COMPREPLY = "" ]] ; then
-            COMPREPLY=( $(compgen -df -- ${cur}) )
+            _filedir
             return 0
         fi
         return 0;
     }
 
     complete -F _cake cake bin/cake
+
+
+Using autocompletion
+====================
+
+Once enabled, the autocompletion can be used the same way than for other
+built-in commands, using the **TAB** key.
+Three type of autocompletion are provided. The following output are from a fresh CakePHP install.
+
+Commands
+--------
+
+Sample output for commands autocompletion::
+
+    $ bin/cake <tab>
+    bake        i18n        orm_cache   routes
+    console     migrations  plugin      server
+
+Subcommands
+-----------
+
+Sample output for subcommands autocompletion::
+
+    $ bin/cake bake <tab>
+    behavior            helper              shell
+    cell                mailer              shell_helper
+    component           migration           template
+    controller          migration_snapshot  test
+    fixture             model
+    form                plugin
+
+Options
+-------
+
+Sample output for subcommands options autocompletion::
+
+    $ bin/cake bake -<tab>
+    -c            --everything  --force       --help        --plugin      -q            -t            -v
+    --connection  -f            -h            -p            --prefix      --quiet       --theme       --verbose
diff --git a/fr/console-and-shells/completion-shell.rst b/fr/console-and-shells/completion-shell.rst
@@ -57,14 +57,43 @@ Par exemple::
 
 Retourne::
 
-    --help -h --verbose -v --quiet -q --connection -c --template -t
+    --help -h --verbose -v --quiet -q --everything --connection -c --force -f --plugin -p --prefix --theme -t
 
-Exemple de Bash
-===============
+Vous pouvez passer un autre argument représentant une sous-commande du shell :
+cela vous retournera les options spécifiques à cette sous-commande.
 
-L'exemple de bash suivant provient de l'auteur original::
+Activer l'autocomplétion Bash pour la console CakePHP
+=====================================================
 
-    # bash completion for CakePHP console
+Tout d'abord, assurez-vous que la librairie **bash-completion** est installée.
+Si elle ne l'est pas, vous pouvez le faire en exécutant la commande suivante::
+
+    apt-get install bash-completion
+
+Créez un fichier **cake** dans **/etc/bash_completion.d/** et placez-y le
+:ref:`bash-completion-file-content`.
+
+Sauvegardez le fichier et rédémarrez la console.
+
+.. note::
+
+    Si vous utilisez MacOS X, vous pouvez installer la librairie
+    **bash-completion** en utilisant **homebrew** avec la commande suivante :
+    ``brew install bash-completion``. Le répertoire cible du fichier **cake**
+    devra être **/usr/local/etc/bash_completion.d/**.
+
+.. _bash-completion-file-content:
+
+Contenu du fichier bash d'autocomplétion
+----------------------------------------
+
+Voici le code que vous devez saisir dans le fichier **cake** (préalablement créé
+au bon emplacement pour bénéficier de l'autocomplétion quand vous utilisez la
+console CakePHP::
+
+    #
+    # Fichier de completion Bash pour la console CakePHP
+    #
 
     _cake()
     {
@@ -97,20 +126,58 @@ L'exemple de bash suivant provient de l'auteur original::
             opts=$(${cake} Completion subcommands $prev)
             COMPREPLY=( $(compgen -W "${opts}" -- ${cur}) )
             if [[ $COMPREPLY = "" ]] ; then
-                COMPREPLY=( $(compgen -df -- ${cur}) )
+                _filedir
                 return 0
             fi
             return 0
         fi
 
-
         opts=$(${cake} Completion fuzzy "${COMP_WORDS[@]:1}")
         COMPREPLY=( $(compgen -W "${opts}" -- ${cur}) )
         if [[ $COMPREPLY = "" ]] ; then
-            COMPREPLY=( $(compgen -df -- ${cur}) )
+            _filedir
             return 0
         fi
         return 0;
     }
 
     complete -F _cake cake bin/cake
+
+Utilisez l'autocompletion
+=========================
+
+Une fois activée, l'autocompletion peut être utilisée de la même manière que
+pour les autres commandes natives du système, en utilisant la touche **TAB**.
+Trois types d'autocompletion sont fournis. Les examples de retour qui suivent
+proviennent d'une installation fraîche de CakePHP.
+
+Commandes
+---------
+
+Exemple de rendu pour l'autocomplétion des commandes::
+
+    $ bin/cake <tab>
+    bake        i18n        orm_cache   routes
+    console     migrations  plugin      server
+
+Sous-commandes
+--------------
+
+Exemple de rendu pour l'autocomplétion des sous-commandes::
+
+    $ bin/cake bake <tab>
+    behavior            helper              shell
+    cell                mailer              shell_helper
+    component           migration           template
+    controller          migration_snapshot  test
+    fixture             model
+    form                plugin
+
+Options
+-------
+
+Exemple de rendu pour l'autocomplétion des options d'une sous-commande::
+
+    $ bin/cake bake -<tab>
+    -c            --everything  --force       --help        --plugin      -q            -t            -v
+    --connection  -f            -h            -p            --prefix      --quiet       --theme       --verbose