core: allow users to set custom-file variable

In this case Spacemacs won't write custom variables to the
dotspacemacs/emacs-custom-settings variable.

Move setq and add-advice to spacemacs/initialize-custom-file which is now
called in spacemacs/init function just after dotspacemacs/user-init function.

core/core-custom-settings.el

@@ -12,11 +12,18 @@
 
 (defvar spacemacs--custom-file (concat spacemacs-cache-directory
                                        ".custom-settings"))
-(setq custom-file spacemacs--custom-file)
 
-(defun spacemacs//initialize-custom-file ()
+(defun spacemacs/initialize-custom-file ()
   "Initialize the custom file."
-  (unless (file-exists-p spacemacs--custom-file)
+  ;; setup auto-rewrite of custom settings only if custom-file
+  ;; has not been set by the user
+  (when (null custom-file)
+    (setq custom-file spacemacs--custom-file)
+    (advice-add 'custom-save-all :after
+                #'spacemacs/write-custom-settings-to-dotfile))
+  ;; initialize the cache file contents
+  (unless (or (not (string-equal custom-file spacemacs--custom-file))
+              (file-exists-p spacemacs--custom-file))
     (with-temp-file spacemacs--custom-file
       (let ((standard-output (current-buffer)))
         (princ ";; -*- mode: emacs-lisp -*-\n")
@@ -91,7 +98,4 @@ This function is called at the very end of Spacemacs initialization.\"\n")
       (save-buffer)
       (kill-buffer (current-buffer)))))
 
-(spacemacs//initialize-custom-file)
-(advice-add 'custom-save-all :after #'spacemacs/write-custom-settings-to-dotfile)
-
 (provide 'core-custom-settings)

core/core-spacemacs.el

@@ -98,6 +98,7 @@ the final step of executing code in `emacs-startup-hook'.")
   ;; effective ones.
   ;; Note: Loading custom-settings twice is not ideal since they can have side
   ;; effects! Maybe an inhibit variable in Emacs can supress these side effects?
+  (spacemacs/initialize-custom-file)
   (dotspacemacs|call-func dotspacemacs/emacs-custom-settings
                           "Calling dotfile Emacs custom settings...")
   (setq dotspacemacs-editing-style (dotspacemacs//read-editing-style-config

doc/DOCUMENTATION.org

@@ -572,10 +572,22 @@ configuration at the beginning and end of Spacemacs loading process:
   your configurations should be done. Unless it is explicitly specified that a
   variable should be set before a package is loaded, you should place your code
   here.
+- =dotspacemacs/emacs-custom-settings= is a generated function where all Emacs
+  custom settings are written. You should not edit this function. See
+ =Custom variables= section for more information.
 
 *** Custom variables
-Custom variables configuration from =M-x customize-group= built-in Emacs feature
-are automatically saved by Emacs at the end of your =~/.spacemacs= file.
+By default custom variables from =M-x customize-group= are automatically saved
+at the end of your =~/.spacemacs= file in the function
+=dotspacemacs/emacs-custom-settings== unless you declare a custom =custom-file=
+in the =dotspacemacs/user-init= function, in this case custom variables will be
+written to the user defined =custom-file= and the function
+=dotspacemacs/emacs-custom-settings= will remain empty.
+
+*Note:* if you set a custom =custom-file= value then it is your responsibility
+to load this file at the appropriate time. Often the best time to load it is
+just after setting the value for =custom-file= in the =dotspacemacs/user-init=
+function.
 
 ** Declaring Configuration layers
 To use a configuration layer, declare it in your dotfile by adding it to the