Django Styleguide

Introduction

Django-styleguide helps you to create and maintain a living styleguide in your django project.
It is designed to be as simple as adding a template file to your project.

Features

Simple configuration: Install it, add the styleguide template folder, it works
Dynamic generation: Do not need to execute a django command, while DEBUG = True it generates each time.
Your code. Your way: 100% configurable. You add the css and js necessary. Checkout the configuration section.

Explanation

Create and maintain a living styleguide is a hard task. If you follow good patterns such as BEM, SMACSS or OOCSS you can have a hard time creating the CSS and maintaining it as the project grows.
A good pattern is creating a styleguide as a way to document your html components and css code.
Big projects such as bootstrap, foundation or purecss has their own styleguide as their frontend's documentation. This django's module helps you to dynamically generate a styleguide for your django project in an easy way.
You can create a template file for each html component you have and sort them using folder as modules.

How to install

To install it, you can use pip as follow:

pip install django-styleguide

Or cloning the github's project direct in your project:

git clone git@github.com:andrefarzat/django-styleguide.git styleguide

Add it in the INSTALLED_APPS list

INSTALLED_APPS = (
    ...
    'styleguide',
)

Then add the styleguide module in the urls list:

urlpatterns = patterns('',
    ...
    url(r'^styleguide/', include('styleguide.urls')),
)

Once you start the server, you can navegate to /styleguide/ and see the initial page.

Getting started

Create a styleguide folder in the templates folder in your django project.
Then, create a folder named basic and add a file name box.html.
Navigate to /styleguide/ and you will see that the box component is shown in the basic module.
That's how you can create modules and components to organize your styleguide.

Creating your own index

Django-styleguide uses the django's template engine to compose the final html.
To replace it you can create the index.html file in styleguide template folder and it will be used instead of the default one (respecting the Template Loader order). In the context, there is a variable called styleguide that has all modules and components.
Here I show you a minimal example for an index.html:

{% for module in styleguide.modules %}
    <h2>Module: {{ module.name }}</h2>

    {% for component in module.components %}
        <section>
            <h3><a href="{{component.link}}">{{ component.name }}</a></h3>

            {% include component.template %}
        </section>
    {% endfor %}

{% endfor %}

You can check the default index.html file to see a more complete example.

Understanding the folder structure (modules and files)

Having folder and files as modules and components follow the python pattern for modules.
You can create any number of folder and subfolder as you wish to organize your components.
This helps not only separating well the components, but also it is possible to create the menu items regarding the modules and also create permalink direct to a module or component.
As an example, if you navigate to the url /styleguide/basic/box you will see only box component from the basic module.

Sorting the result

The order which the modules and components are shown is very important.
They are always sorted alphabetically, however, you can sort them using a number prefix in the folder or file.
Let's say you have three template files inside the basic folder: box, table sorter and list.
If you need to define an order, you prefix them using two number and a dash such as 01-list.html. The name will be formatted removing this prefix from all files and folder. This way you can deternime any order you want.
In the same way, undercores and dashes will be conveted to white spaces.

01-list.html #  will be shown as 'list'
02-table_sorter.html #  will be shown as 'table sorter'
box.html #  will be shown as 'box'

Configure

There are a few configuration variables that you can overwritten.

# Debug flag for styleguide ( e.g.: if True, the styleguide generation is not cached )
STYLEGUIDE_DEBUG = settings.DEBUG

# The name of the styleguide directory in templates folder
STYLEGUIDE_DIR_NAME = 'styleguide'

# The name used to cache the execution
STYLEGUIDE_CACHE_NAME = 'styleguide_components'

# A tuple with folder names to be ignored
STYLEGUIDE_IGNORE_FOLDERS = ('includes', )

# A small function to validate the access to the user
STYLEGUIDE_ACCESS = lambda user: user.is_staff or user.is_superuser