Add Naked setup mode

djangocms_helper/main.py

@@ -25,13 +25,14 @@
 
 Usage:
     djangocms-helper <application> test [--failfast] [--migrate] [--no-migrate] [<test-label>...] [--xvfb] [--runner=<test.runner.class>] [--extra-settings=</path/to/settings.py>] [--cms] [--nose-runner] [--simple-runner] [--runner-options=<option1>,<option2>] [--native] [--boilerplate] [options]
-    djangocms-helper <application> cms_check [--extra-settings=</path/to/settings.py>] [--migrate] [--no-migrate] [--boilerplate]
+    djangocms-helper <application> cms_check [--extra-settings=</path/to/settings.py>] [--cms] [--migrate] [--no-migrate] [--boilerplate]
     djangocms-helper <application> compilemessages [--extra-settings=</path/to/settings.py>] [--cms] [--boilerplate]
     djangocms-helper <application> makemessages [--extra-settings=</path/to/settings.py>] [--cms] [--boilerplate]
     djangocms-helper <application> makemigrations [--extra-settings=</path/to/settings.py>] [--cms] [--merge] [--empty] [--dry-run] [--boilerplate] [<extra-applications>...]
     djangocms-helper <application> pyflakes [--extra-settings=</path/to/settings.py>] [--cms] [--boilerplate]
     djangocms-helper <application> authors [--extra-settings=</path/to/settings.py>] [--cms] [--boilerplate]
     djangocms-helper <application> server [--port=<port>] [--bind=<bind>] [--extra-settings=</path/to/settings.py>] [--cms] [--boilerplate] [--migrate] [--no-migrate] [--persistent[=path]]
+    djangocms-helper <application> setup [--extra-settings=</path/to/settings.py>] [--cms] [--boilerplate]
     djangocms-helper <application> <command> [options] [--extra-settings=</path/to/settings.py>] [--cms] [--boilerplate] [--migrate] [--no-migrate]
 
 Options:
@@ -257,6 +258,10 @@ def server(bind='127.0.0.1', port=8000, migrate_cmd=False):  # pragma: no cover
     })
 
 
+def setup_env(settings):
+    return settings
+
+
 def core(args, application):
     from django.conf import settings
 
@@ -325,8 +330,7 @@ def null_context():
                                             args['--runner-options'])
                         sys.exit(num_failures)
                 elif args['server']:
-                    server(args['--bind'], args['--port'],
-                           args.get('--migrate', True))
+                    server(args['--bind'], args['--port'], args.get('--migrate', True))
                 elif args['cms_check']:
                     cms_check(args.get('--migrate', True))
                 elif args['compilemessages']:
@@ -341,6 +345,8 @@ def null_context():
                     return static_analisys(application)
                 elif args['authors']:
                     return generate_authors()
+                elif args['setup']:
+                    return setup_env(settings)
 
 
 def main(argv=sys.argv):  # pragma: no cover
@@ -372,6 +378,6 @@ def main(argv=sys.argv):  # pragma: no cover
             args['test'] = False
             args['<command>'] = 'test'
             args['options'].remove('--native')
-        core(args=args, application=application)
+        return core(args=args, application=application)
     else:
         args = docopt(__doc__, version=__version__)

djangocms_helper/runner.py

@@ -5,14 +5,14 @@
 import os.path
 import sys
 
-from . import HELPER_FILE
-
 
 def run(app, argv=sys.argv, extra_args=None):
     """
-    Function to invoke to run commands in a plain django environment
+    Run commands in a plain django environment
 
     :param app: application
+    :param argv: arguments (default to sys.argv)
+    :param extra_args: list of extra arguments
     """
     if app not in argv[:2]:
         # app is automatically added if not present
@@ -27,9 +27,11 @@ def run(app, argv=sys.argv, extra_args=None):
 
 def cms(app, argv=sys.argv, extra_args=None):
     """
-    Function to invoke to run commands in a django CMS environment
+    Run commands in a django cMS environment
 
     :param app: application
+    :param argv: arguments (default to sys.argv)
+    :param extra_args: list of extra arguments
     """
     try:
         import cms  # NOQA  # nopyflakes
@@ -50,7 +52,27 @@ def cms(app, argv=sys.argv, extra_args=None):
     return runner(argv)
 
 
+def setup(app, helper_module, extra_args=None, use_cms=False):
+    """
+    Setup the Django / django CMS environment and return the environment settings.
+
+    :param app: application
+    :param helper_module: helper module
+    :param extra_args: list of extra arguments
+    :param use_cms: setup a django CMS environemtn
+    :return: Django settings module
+    """
+    helper = helper_module.__file__
+    argv = [os.path.basename(helper), app, 'setup', '--extra-settings={0}'.format(helper)]
+    if use_cms:
+        argv.append('--cms')
+    if extra_args:
+        argv.extend(extra_args)
+    return runner(argv)
+
+
 def runner(argv):
+    from . import HELPER_FILE
     from .main import main
 
     # This is a hackish way to get the caller file which is the file

djangocms_helper/test_utils/cms_helper.py

@@ -44,5 +44,11 @@ def run():
     from djangocms_helper import runner
     runner.cms('example1')
 
+
+def setup():
+    import sys
+    from djangocms_helper import runner
+    runner.setup('example1', sys.modules[__name__], use_cms=True)
+
 if __name__ == "__main__":
     run()

djangocms_helper/tests/test_commands.py

@@ -519,6 +519,13 @@ def fake_runner(argv):
                         data = runner.run('example1', args)
                     self.assertEqual(data, [u'djangocms_helper', u'example1', u'test'])
 
+    def test_setup(self):
+        with work_in(self.basedir):
+            with captured_output() as (out, err):
+                from djangocms_helper.test_utils import cms_helper
+                settings = runner.setup('example1', cms_helper)
+        self.assertTrue('example2' in settings.INSTALLED_APPS)
+
     @unittest.skipIf(sys.version_info < (2, 7),
                      reason='Example test non discoverable in Python 2.6')
     @unittest.skipIf(LooseVersion(django.get_version()) >= LooseVersion('1.8'),

djangocms_helper/utils.py

@@ -55,8 +55,7 @@ def load_from_file(module_path):
     imported = None
     if module_path:
         with open(module_path, 'r') as openfile:
-            imported = load_module('mod', openfile, module_path,
-                                   ('imported', 'r', PY_SOURCE))
+            imported = load_module('mod', openfile, module_path, ('imported', 'r', PY_SOURCE))
     return imported
 
 
@@ -157,7 +156,8 @@ def _make_settings(args, application, settings, STATIC_ROOT, MEDIA_ROOT):
         if not extra_settings_file:
             extra_settings_file = HELPER_FILE
         if extra_settings_file[-3:] != '.py':
-            extra_settings_file = '%s.py' % extra_settings_file
+            filename, __ = os.path.splitext(extra_settings_file)
+            extra_settings_file = '{0}.py'.format(filename)
         extra_settings = load_from_file(extra_settings_file).HELPER_SETTINGS
     except (IOError, AttributeError):
         extra_settings = None

docs/conf.py

@@ -18,7 +18,9 @@
 # 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
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-sys.path.insert(0, os.path.abspath('..'))
+sys.path.insert(0, os.path.abspath('../djangocms_helper/test_utils'))
+import cms_helper
+cms_helper.setup()
 
 # -- General configuration ------------------------------------------------
 

docs/index.rst

@@ -21,6 +21,7 @@ The utilities provided:
 * help manage Django and South migrations
 * perform static analysis using pyflakes
 * build an authors list automatically
+* setting up a Django environment
 
 django CMS Helper was created by Iacopo Spalletti.
 
@@ -66,4 +67,4 @@ Requirements
    basetest
    development
    contributing
-   history
+   history

docs/introduction.rst

@@ -76,7 +76,7 @@ Try a couple of the other commands; they're mostly self-explanatory::
 
     djangocms-helper <myapp> cms_check  # runs the django CMS check command
 
-Note that the last of these doesn't take the ``--cms`` option, because of course that is implied
+Note that the last of these doesn't require the ``--cms`` option, because of course that is implied
 anyway by ``cms_check``.
 
 
@@ -99,4 +99,22 @@ Or::
 
 to invoke a server.
 
-See :doc:`runner` for details.
+See :doc:`runner` for details.
+
+
+==================
+Sphinx integration
+==================
+
+When documenting a project using Sphinx autodoc, you mostly need a proper project setup, because
+the imports in your application's modules will trigger Django setup code anyway.
+
+Using the :ref:`naked_runner` it's easy to let helper setup an environment for you:
+
+* setup the :ref:`naked_runner`
+* add the following code to sphinx ``conf.py``::
+
+    sys.path.insert(0, os.path.abspath('..'))
+    import cms_helper
+    cms_helper.setup()
+

docs/runner.rst

@@ -59,4 +59,23 @@ If you don't need django CMS, you can use a runner function with no CMS attached
 
 .. warning:: The runner **must** be invoked from the **settings** file.
              The runner takes care of setting up the file in which is
-             invoked as the ``extra_settings`` file.
+             invoked as the ``extra_settings`` file.
+
+.. _naked_runner:
+
+Naked setup
+===========
+
+Sometimes you just want to properly setup a Django environment without running any commands
+(e.g: when building Sphinx docs using autodoc). Naked setup allows to do so::
+
+
+    def setup():
+        import sys
+        from djangocms_helper import runner
+        runner.setup('my_app', sys.modules[__name__], use_cms=True)
+
+
+.. warning:: The runner **must** be invoked from the **settings** file.
+             The runner takes care of setting up the file in which is
+             invoked as the ``extra_settings`` file.