auto-completion layer: update README

contrib/auto-completion/README.md

@@ -7,6 +7,10 @@
     - [Description](#description)
     - [Install](#install)
         - [Company variables](#company-variables)
+    - [Configure](#configure)
+        - [Enable company or auto-complete globally](#enable-company-or-auto-complete-globally)
+        - [Replacing company by auto-complete](#replacing-company-by-auto-complete)
+        - [Add auto-completion in a layer](#add-auto-completion-in-a-layer)
     - [Key Bindings](#key-bindings)
         - [Company](#company)
         - [Auto-complete](#auto-complete)
@@ -16,18 +20,14 @@
 ## Description
 
 This layer provides auto-completion to Spacemacs.
-The following front-ends are supported:
+
+The following completion engines are supported:
 - [company][]
 - [auto-complete][]
 
-**Notes**
-- `company` is the preferred front-end in Spacemacs.
-- For a given language, Spacemacs supports one and only one front-end (hopefully
-the best).
-
 ## Install
 
-To use this contribution add it to your `~/.spacemacs`
+To use this configuration layer add it to your `~/.spacemacs`
 
 ```elisp
 (setq-default dotspacemacs-configuration-layers '(auto-completion))
@@ -52,6 +52,65 @@ to `t`
 (setq-default dotspacemacs-configuration-layers
   '(auto-completion :variables
                     auto-completion-enable-company-help-tooltip t))
+
+## Configure
+
+### Enable company or auto-complete globally
+
+By default Spacemacs enables auto-completion explicitly for each supported
+major-mode, it means that `company` and `auto-complete` are not enabled
+globally, it allows more flexibility to choose an auto-completion engine
+for a given mode.
+
+You may want to enable company globally to get auto-completion
+everywhere even in the modes which are not configured by Spacemacs. To do
+so, you just have to add `(global-company-mode)` in the
+`dotspacemacs/config` function of your dotfile.
+
+Note that if you want to enable auto-complete globally you will have to
+disable company first, see the next section to do so.
+
+### Replacing company by auto-complete
+
+You can disable company by adding it to the `dotspacemacs-excluded-packages`
+variable, then you are free to configure auto-complete and enable it
+globally.
+```
+
+### Add auto-completion in a layer
+
+Here is an example to add `company` auto-completion to python buffer:
+
+In `config.el`:
+
+```elisp
+;; Define the buffer local company backend variable
+(spacemacs|defvar-company-backends python-mode)
+```
+
+In `packages.el`:
+
+```elisp
+;; Add the relevant packages to the layer
+(defvar python-packages
+  '(...
+    company
+    company-anaconda
+    ...))
+
+;; Configure the packages
+(when (configuration-layer/layer-usedp 'auto-completion)
+
+  ;; Hook company to python-mode
+  (defun python/post-init-company ()
+    (spacemacs|add-company-hook python-mode))
+
+  ;; Add the backend to the major-mode specific backend list
+  (defun python/init-company-anaconda ()
+    (use-package company-anaconda
+      :if (configuration-layer/package-usedp 'company)
+      :defer t
+      :init (push 'company-anaconda company-backends-python-mode))))
 ```
 
 ## Key Bindings