Merge pull request #200 from nephila/feature/config_docs

Add config docs

AUTHORS.rst

@@ -13,6 +13,7 @@ Contributors
 ------------
 
 * Aaron Boman
+* Alexander Pervakov
 * Carlo Ascani <[email protected]>
 * Claudio Luck
 * Enkel Mitrushi

HISTORY.rst

@@ -3,6 +3,19 @@
 History
 -------
 
+0.8.0 (XXXX-XX-XX)
+++++++++++++++++++
+
+* Options can now be provided via an ini file for easy scripting
+* Better migration modules discovery strategy
+* Minor fixes
+
+0.7.9 (2015-07-21)
+++++++++++++++++++
+
+* Better Django 1.8 support
+* Fix error with newer Pillow versions
+
 0.7.8 (2015-06-27)
 ++++++++++++++++++
 

djangocms_installer/__init__.py

@@ -2,4 +2,4 @@
 # -*- coding: utf-8 -*-
 __author__ = 'Iacopo Spalletti'
 __email__ = '[email protected]'
-__version__ = '0.7.9dev1'
+__version__ = '0.8.0.dev3'

docs/conf.py

@@ -12,7 +12,8 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys, os
+import os
+import sys
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the

docs/faq.rst

@@ -27,7 +27,8 @@ FAQ
    **djangocms-installer** uses `dj-database-url`_ to get database
    configuration parameters; refer to this package for more details.
 
-#. The installer dies with an error like ``ImportError: Could not import settings 'foo.bar.settings' (Is it on sys.path? Is there an import error in the settings file?): No module named foo.bar.settings``,
+#. The installer dies with an error like
+   ``ImportError: Could not import settings 'foo.bar.settings' (Is it on sys.path? Is there an import error in the settings file?): No module named foo.bar.settings``,
    what's happening?
 
    Chances are you have ``DJANGO_SETTINGS_MODULE`` set in you environment,

docs/reference.rst

@@ -57,6 +57,9 @@ advanced usage:
 
 * ``--no-input``, ``-q``: If given **djangocms installer** run in :ref:`batch_mode`;
 * ``--filer``, ``-f``: Install and configure django-filer plugins;
+* ``--config-file``: Provides the configuration options via a ini file; see :ref:`ini_mode`;
+* ``--config-dump``: Dumps the configuration in a format suitable for ``-config-file``
+  option; see :ref:`ini_mode`;
 * ``--dump-requirements``, ``-R``: Dumps the generated requirements to stdout
   and exits; see :ref:`dump_mode`;
 * ``--requirements``, ``-r``: You can use a custom requirements files instead of the
@@ -71,11 +74,11 @@ advanced usage:
   project;
 * ``--extra-settings``: Path to a file with extra variables to append to generated settings file.
   It doesn't need to be a Python file, its content is blindly copied in the project settings.
-*``--aldryn``, ``-a``: Use `aldryn-boilerplate`_; this downloads **aldryn-boilerplate** and copies
+* ``--aldryn``, ``-a``: Use `aldryn-boilerplate`_; this downloads **aldryn-boilerplate** and copies
   it to the project, adapting the project layout according to boilerplate specifications; the use
   of aldryn-boilerplate requires manual actions, look at `aldryn-boilerplate documentation`_ for
   further informations.
-*``--skip-empty-check``, ``-s``: Skip the check if the project dir contains files or directory;
+* ``--skip-empty-check``, ``-s``: Skip the check if the project dir contains files or directory;
   in case of error when setting up the project, ``djangocms-installer`` may ask you to remove
   the directory, be careful if using this option as you may remove files not related to the
   project set up by the installer.

docs/usage.rst

@@ -58,6 +58,51 @@ This can be helpful to customize the virtualenv:
 
 See :ref:`arguments` for arguments reference
 
+.. _ini_mode:
+
+Config file mode
+----------------
+
+In config file mode, all (or some) options can be provided via an external configuration file.
+
+See a `complete example`_
+with all available arguments.
+
+Is it possible to either provide all the values in the config file:
+
+.. code-block:: shell
+
+    djangocms_installer --config-file /path/to/config.ini project_name
+
+Or just some, or overriding by using the command line arguments:
+
+.. code-block:: shell
+
+    djangocms_installer --config-file /path/general-config.ini -p /path/other/proj -s -q project_name
+
+.. note:: If config.ini not contains `no-input = true` and `-q` argument isn't set then one
+          act as a placeholder with default values for wizard.
+
+
+Dump config files
+^^^^^^^^^^^^^^^^^
+
+Values passed to the installer can be dumped for later reuse:
+
+.. code-block:: shell
+
+    djangocms_installer --config-dump /path/config.ini -p . project_name
+
+if installation fails dump can be used to fix some arguments and re-run installer with dumped config:
+
+.. code-block:: shell
+
+    djangocms_installer --config-dump /path/config.ini --db postgres://wrong-usr:pwd@host/db -p . project_name
+    # fails
+
+    djangocms_installer --config-file /path/config.ini --db postgres://correct-user:pwd@host/db -p . project_name
+    # succeed
+
 Custom settings
 ---------------
 
@@ -106,4 +151,6 @@ Use different templates directory
 
 You can create the base project with a custom templateset by using the ``--templates`` parameter.
 Be aware that while **djangocms installer** will copy the files for you, it won't update the ``CMS_TEMPLATES`` settings
-parameter, so you'll need to modify that after installation.
+parameter, so you'll need to modify that after installation.
+
+.. _complete example: https://github.com/nephila/djangocms-installer/blob/develop/config.ini.sample