Living Styleguide

Example of living Styleguide made with Flask-Styleguide and Frozen-Flask. This guide describes how to generate your own styleguide for any flask application.

Use KSS to document your stylesheets. KSS is documentation syntax for any flavor CSS. It's human readable, machine parsable, and easy to remember. Flask-Styleguide looks for any KSS formated documentation in static directories of your application and registered blueprints (if any).

// A standard, but classy, button used widely for submit forms and
// to complete other app actions.
//
// :hover - Hover state.
// :active - When the button is pressed.
// :focus - When the button is focused.
// :disabled - Disabled state.
// .is-disabled - Same as above.
//
// Styleguide 2.1.

Define endpoint for your styleguide in application:

@app.route('/styleguide/')
def styleguide():
    return render_template('styleguide.html')

The new jinja tag styleguide becomes available when flask_styleguide is initialized. Let's write some html examples for our buttons:

{% extends 'layout.html' %}
{% block main %}
  {% styleguide "2.1" %}
    <button class="button$modifier_class">Button</button>
    <a class="button$modifier_class">A button link</a>
  {% endstyleguide %}
{% endblock %}

The styleguide/section.html template will be used for each section in your styleguide (like 2.1 in the previous step). Let's define it:

<article class="style-guide" id="{{ section.section }}">
  <h4 class="style-guide-reference">{{ section.section }}</h4>

  <div class="style-guide-description">
    <p>{{ section.description|safe }}</p>
    {% if section.modifiers %}
      <ul class="style-guide-modifiers">
        {% for m in section.modifiers %}
          <li><strong>{{ m.name }}</strong> - {{ m.description }}</li>
        {% endfor %}
      </ul>
    {% endif %}
  </div>

  <div class="style-guide-element">
    {{ section.example|safe }}
  </div>

  {% for m in section.modifiers %}
    <div class="style-guide-element">
      <small class="style-guide-modifier">{{ m.name }}</small>
      {{ m.example|safe }}
    </div>
  {% endfor %}

  <div class="style-guide-html">
    <pre>{{ section.example|forceescape }}</pre>
  </div>
</article>

Prettify styleguide. Without styles styleguide looks not so great. Apply some styling to it or reuse this one:
```
bower install --save classy-style-guide
```
```
@import 'classy-style-guide/components.style-guide.less';
```
Now that you’re up and running. Fire up a browser and go to the brand new styleguide...

vitalk/flask-styleguide-example

Living Styleguide