Metadata-Version: 1.1
Name: django-brunch
Version: 0.0.9
Summary: Integrate a Brunch workflow with Django.
Home-page: https://github.com/nshafer/django-brunch
Author: Nathan Shafer
Author-email: nate-github@lotech.org
License: BSD License
Description: Brunch with Django
        ==================
        
        Integrate a [Brunch](http://brunch.io/) workflow with [Django](https://www.djangoproject.com/).
        
        This replaces the `runserver` management command with a version that fires up a `brunch watch` process alongside the
        Django development server to automatically recompile css and javascript. The brunch process is not interrupted when
        the Django server reloads, but it will die when you shut down down the Django server.
        
        
        Features
        --------
        
        - Run the Django development web server and brunch watch with one command in one window
        - Leaves Brunch completely decoupled from Django, so there is no interdependency between the two. This is simply a
        convenience module.
        - Can optionally enable the brunch server so that brunch plugins like `auto-reload-brunch` will do live reloading of
        app assets such as CSS and Javascript upon saving. Set up brunch to also watch your templates and/or views to get
        live-reloading on modification of anything.
        
        
        Integrate brunch in your Django project
        ---------------------------------------
        
        1. Initialize brunch in your Django project directory. This skeleton will create a brunch-config.js and package.json
        file in the root of your project directory.
        
            ```
            cd myproject
            brunch new -s https://github.com/nshafer/django-brunch-skeleton
            ```
        
        2. Put your CSS and JS files in `static/`, images and other files in `static/assets/`
        
        3. Test brunch. This will output to `brunch/`
        
            ```
            brunch build
            ```
        
        4. Add brunch's output directory `brunch/` to the STATICFILES_DIRS list so that Django will find the files that Brunch
        will create. Remove any existing reference to `static/` since we now only want to include assets handled by brunch.
        
            ```python
            STATICFILES_DIRS = [
                os.path.join(BASE_DIR, "brunch"),
            ]
            ```
        
        5. Link the brunch output in your templates
        
            ```html
            <link rel="stylesheet" href="{% static "app.css" %}"/>
            <script src="{% static "app.js" %}"></script>
            ```
        
        
        Install the Django Module
        -------------------------
        
        1. Install 'django-brunch' from PyPI
        
            ```
            pip install django-brunch
            ```
            
        2. Add `brunch` to INSTALLED_APPS, but BEFORE `django.contrib.staticfiles`:
        
            ```python
            INSTALLED_APPS = [
                ...
                'brunch',
                ...
                'django.contrib.staticfiles'
            ]
            ```
        
        3. Configure django-brunch in your settings.py file. At a minimum, `BRUNCH_DIR` must be defined. This needs to be an
        absolute path to the directory where your `brunch-config.js` or `brunch-config.coffee` file lives.
        
            ```python
            BRUNCH_DIR = BASE_DIR
            ```
            
        4. Run `runserver` like you normally would. A brunch process will be started alongside the Django development web server
        in the directory you provided with BRUNCH_DIR. One terminal, both processes!
        
            ```
            ./manage.py runserver
            ```
        
        
        Live Reloading
        --------------
        
        By default, the 'brunch-config.js' that is installed from
        [django-brunch-skeleton](https://github.com/nshafer/django-brunch-skeleton)
        will enable auto-reloading upon modification of files in `static/` and `template/` as long as you enable
        `BRUNCH_SERVER` in your Django settings.
        Add your individual app static and template directories to `paths.watched` to get the same for all of your apps.
        
        
        Building for production
        -----------------------
        
        Building for production will be much the same, with just one extra step to do before you run `collectstatic`. You need
        to have brunch build a final production version of your assets.
        
        ```
        brunch build --production
        ./manage.py collectstatic
        ```
        
        
        Settings
        --------
        
        ### BRUNCH_DIR (required)
        
        This should be an absolute path to the location of your brunch directory; where your `brunch-config.js` or
        `brunch-config.coffee` file lives.
        
        Example:
        
        ```python
        BRUNCH_DIR = os.path.join(BASE_DIR, "brunch")
        ```
        
        ### BRUNCH_CMD (optional)
        
        Default:
        
        ```python
        BRUNCH_CMD = ("/usr/bin/env", "brunch")
        ```
        
        This is the location of your `brunch` CLI command. It is passed to
        [subprocess.Popen](https://docs.python.org/3.4/library/subprocess.html#popen-constructor) so it needs to either be a
        string or a sequence type (list, tuple). It is recommended that this is a tuple or list of arguments so that
        we can spawn it without involving shell parsing. If it is a string AND the string has a space or other shell characters,
        then you will need to set BRUNCH_SHELL to True as well, so that Popen knows to spawn a shell to parse the command.
        
        If you install brunch as a local dependency in the local `node_modules` directory, then you'll probably want something
        like this:
        
        ```python
        BRUNCH_CMD = os.path.join(BASE_DIR, "brunch", "node_modules", "brunch", "bin", "brunch")
        ```
        
        ### BRUNCH_SHELL (optional)
        
        Default:
        
        ```python
        BRUNCH_SHELL = False
        ```
        
        If your BRUNCH_CMD requires a shell to parse, then set this to True. This is passed directly to
        [subprocess.Popen](https://docs.python.org/3.4/library/subprocess.html#popen-constructor)'s `shell` argument. For
        example, this needs to be True if your BRUNCH_CMD has a space in it or any other kind of special shell syntax.
        
        ### BRUNCH_SERVER (optional)
        
        Default:
        
        ```python
        BRUNCH_SERVER = False
        ```
        
        If this is enabled, then the `brunch watch` command will be started with the `--server` argument. This will instruct
        Brunch to start up its internal server alongside Django's. This shouldn't be needed in a lot of cases, however one very
        useful time for this is if you're using the "auto-reload-brunch" plugin in brunch. If you are, then enabling the brunch
        server will allow it to inform the browser of changes to your assets and do live reloads.
        
        
        Example project
        ---------------
        
        To run the example Django project, follow these steps
        
        1. Create a new virtualenv (assuming [virtualenvwrapper](https://virtualenvwrapper.readthedocs.org/en/latest/))
        
            ```
            mkvirtualenv django-brunch-example
            ```
        
        2. Clone the github repository and install requirements
        
            ```
            git clone https://github.com/nshafer/django-brunch.git
            cd django-brunch/example
            pip install -r requirements.txt
            npm install
            ```
        
        3. Migrate if needed
        
            ```
            ./manage.py migrate
            ```
        
        4. Run the server and brunch
        
            ```
            ./manage runserver
            ```
        
        5. Log in to http://localhost:8000 and see them working together. Modify the stylesheet in `static/style/site.css` and
        save it to live reloading in action. If you need to get in to the admin, the username and password are 'admin'.
        
        
Keywords: django brunch
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 1.8
Classifier: Framework :: Django :: 1.9
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
