Style documenation syntax

Documentation format

Format overview

/*
title (first line)

description (multiple lines)

Example: (followed by the lines of the example indented by at least 2 spaces)

Styleguide <reference - I.E.: components.button>
*/

A full example (using sass):

/*
Buttons

We provide several different kinds of buttons.

Example:
    <button class="button">Default</button>
    <button class="button button--primary">Primary</button>
    <button class="button button--secondary">Secondary</button>

Styleguide components.button
*/
.button {
    // Your styles here

    &--primary {
        // Your styles here
    }

    &--secondary {
        // Your styles here
    }

    &:hover {
        // Your hover styles here
    }
}

Title

The first line in the comment is the title.

Description

Description is optional. It is written using Markdown. See Markdown format for details about the markdown format.

Reference

The reference must be a unique dotted path for the section.

Examples:

/* Buttons

Styleguide buttons
*/

/* Primary button

Styleguide buttons.primary
*/


/* Default button

Styleguide buttons.button
*/

Sorting sections

The styleguide is grouped and sorted by the reference. If you want to override how a reference is sorted, you can use <number>:<text> for the last part of the reference. E.g.:

/* Buttons

Styleguide 1:buttons
*/

/* Primary button

Styleguide buttons.1:primary
*/


/* Default button

Styleguide buttons.2:button
*/


/* Danger button
I do not care how this is sorted. It will be sorted after
the explicitly sorted "Primary button" and "Default button".

Styleguide buttons.danger
*/

The <number>:<text> format can only be used for the last part of the reference path.

Note

You can, alternatively, use numbers instead of text for the reference path, but this is a pain to keep organized in any larger project.

Example

An Earkup section is a (typically syntax hilighted) example. You start an Example part with Example: and any line indented by at least 2 spaces below that line is part of the markup.

Simple example:

Example:
    <button class="default">Default button</button>
    <button class="primary">Primary button</button>

Example syntax

The default syntax is html, but you can override this with Example: (<syntax>) where <syntax> is the same as for Markdown code blocks. Example using scss syntax:

Example: {syntax: scss}
    .my-primary-button {
        @include button-primary();
    }

You can also provide a title for your markup parts. This is mostly useful when you have multiple markup parts in a section:

Example: In HTML
    <button class="default">Default button</button>
    <button class="primary">Primary button</button>

Example: {syntax: scss} Using the mixins
    .my-primary-button {
        @include button-primary();
        color: red;
    }

Example type

You can specify a type to indicate the type of your example. We recommend that all styleguide renderers using pythonkss at least support:

  • embedded (the default): Embed the preview HTML within the styleguide.
  • isolated: Isolated preview typically opened in a new window or iframe with the example code in the body of the page.

Using the isolated type:

Example: {type: isolated} An isolated example
    <nav class="mainnavigation">
        <a href="#">Page 1</a>
        <a href="#">Page 2</a>
    </nav>

Code-only examples and preview-only examples

You can control if your example should be shown as:

  • A preview.
  • Code only (normally syntax hilighted)
  • Both (the default when syntax is html)

The preview and code options in action:

Example: With both preview and (syntax hilighted) code
    <h1>This is the primary heading</h1>

Example: {preview: false} Without preview - code only
    <h1>This is the primary heading</h1>

Example: {code: false} Without code - preview only
    <h1>This is the primary heading</h1>

Example: {syntax: css} Syntax other than HTML - preview is off by default!
    .stuff {
        color: red;
    }

Markdown format

Paragraphs

Paragraphs are just one or more lines of consecutive text followed by one or more blank lines:

Maecenas faucibus mollis interdum. Vestibulum id ligula porta felis euismod
semper. Vestibulum id ligula porta felis euismod semper. Aenean lacinia
bibendum nulla sed consectetur.

Donec id elit non mi porta gravida at eget metus. Vestibulum id ligula
porta felis euismod semper. Praesent commodo cursus magna, vel scelerisque
nisl consectetur et.

Headings

# Largest heading
## Second largest heading
### Third heading

Note

In markdown, these formats normally would result in H1, H2 and H3 tags, but our parser converts these to H3, H4 and H5 to make it easier to integrate docs in a page. This is because the typical use case is to have a H1 at the top of the page and a H2 for each section. This means that any text in a description should be H3 to be semantically correct.

To change this behavior, make a subclass of pythonkss.markdownformatter.MarkdownFormatter, override postprocess_html() and use your own MarkdownFormatter subclass with pythonkss.section.Section.description() as input instead of using pythonkss.section.Section.description_html().

Text styles

*Italic text*
_Italic text_

**Bold text**
__Bold text__

Lists

Unordered lists (bullet lists):

* This
* is
* a
* test

Ordered lists (numbered lists):

1. Item one
2. Item two
3. Item three

Definition lists:

Apple
:   Pomaceous fruit of plants of the genus Malus in
    the family Rosaceae.

Orange
:   The fruit of an evergreen tree of the genus Citrus.

Blockquotes

As stated on the first page of the 101 guide:

> You have to learn to walk before you can learn how to run

HTML mixed with the Markdown

We do not strip HTML from the markdown, so you can do stuff like this:

Button style examples:

- <button>Default button</button>
- <button class="primary">Primary button</button>

Markdown syntax does not work within a HTML element.

Escape Markdown characters

If you want to use a special Markdown character in your document (such as displaying literal asterisks), you can escape the character with a backslash. Markdown will ignore the character directly after a backslash. Example:

This is how the \_ (underscore) and \* asterisks characters look.

Code blocks

You can easily show syntax highlighted code blocks:

JavaScript:
HTML:
``` html
<h1 class="xlarge">Hello world</h1>
```

CSS:
``` css
body {
    background-color: pink;
    color: green;
    font-size: 80px;
}
```

SASS (scss):
```scss
.button {
    font-size: 14px;
    padding: 6px 12px;
    &--large {
        font-size: 20px;
        padding: 10px 20px;
    }
}
```

LESS:
```less
.button {
    font-size: 14px;
    padding: 6px 12px;
    &.button--large {
        font-size: 20px;
        padding: 10px 20px;
    }
}
```

``` javascript
function helloworld() {
    var message = "Hello World";
    console.log(message);
}
```

Not hilighted:
```
for x in 1 through 3
    show x
```

We support all languages supported by Pygments. The actual name of each language can be found in the pygments lexer docs.

Extending styleguide sections

Lets say you are using a base theme, and you want to:

  • Add some text to some of the sections in the base theme.
  • Replace some of the sections with your own docs.

We actually provide 4 section types:

  • Styleguide: The base docs for a section. As seen in all the examples previously in this guide.
  • StyleguideExtendBefore: Extend the docs of a section adding the new docs before existing docs.
  • StyleguideExtendAfter: Extend the docs of a section adding the new docs after existing docs.
  • StyleguideReplace: Replace the docs for a section.

StyleguideExtendBefore and StyleguideExtendAfter

Any section using one of these section types will be merged with the base docs for the section. This means that any:

  • title
  • description
  • example

will be added before or after the original base docs for the section. They are merged as follows:

  • Any title is added before or after the original title. The orignal and the added content is separated by a single space.
  • Any description is added before or after the original description. The orignal and the added content is separated by two newline characters.
  • Any examples is added before or after the original examples. Examples is a list, so for examples we just insert to the beginning or append to the end of the list.

Titles must be marked with Title: <new title here>. This is bacause the parser must have some way of knowing if you are overriding a description or a title. Titles must still be on the first non-empty line of the comment.

Basic example

The following:

/*
Buttons

We provide several different kinds of buttons.

Example:
    <button class="button">Default</button>

Styleguide components.button
*/


/*
Some extra description added after the original description!

Example:
    <button class="button">An extra example added after the original example</button>

Example:
    <button class="button">Another extra example added after the original example</button>

StyleguideExtendAfter components.button
*/


/*
Some extra description added before the original description!

Example:
    <button class="button">An extra example added before the original example</button>

StyleguideExtendBefore components.button
*/

Will result in the components.button section ending up with the following content:

/*
Buttons

Some extra description added before the original description!

We provide several different kinds of buttons.

Some extra description added after the original description!

Example:
    <button class="button">An extra example added before the original example</button>

Example:
    <button class="button">Default</button>

Example:
    <button class="button">An extra example added after the original example</button>

Example:
    <button class="button">Another extra example added after the original example</button>

Styleguide components.button
*/

Adding a prefix and suffix to the title

The following:

/*
Buttons

We provide several different kinds of buttons.

Example:
    <button class="button">Default</button>

Styleguide components.button
*/


/*
Title: DEPRECATED

StyleguideExtendAfter components.button
*/


/*
Title: (do not use for new code)

StyleguideExtendAfter components.button
*/

Will result in the components.button section ending up with the following content:

/*
DEPRECATED Buttons (do not use for new code)

We provide several different kinds of buttons.

Example:
    <button class="button">Default</button>

Styleguide components.button
*/

StyleguideReplace

A section of this type will replace any base section.

The following:

/*
Buttons

We provide several different kinds of buttons.

Example:
    <button class="button">Default</button>

Styleguide components.button
*/

/*
Our buttons

They are very cool.

StyleguideReplace components.button
*/

Will result in the Styleguide components.button section beeing replaced by the StyleguideReplace components.button section. So the original will not be included in the style guide.

Parse order for extending styleguide sections

To understand this, you need to understand about styleguide parse order:

The styleguide parser gets one or more directories as input. If you only use one directory, you should not be messing around with extending at all because order can only be guaranteed per directory.

If you provide multiple directories, they are parsed in the provided order. This means that all files in the first directory is parsed before parsing the second directory (and so on).

So if you are extending a base theme, the base theme should be the first directory parsed, and your custom/extended styles should be last.

So with this in mind, you should be able to understand the rules when extending styleguide sections:

  • The last StyleguideReplace will replace any section with the same reference. If you have multiple StyleguideReplace, the last one will be used and all others is ignored.
  • StyleguideReplace will ignore any StyleguideExtendBefore and StyleguideExtendAfter sections.
  • The merge of StyleguideExtendBefore and StyleguideExtendAfter into normal sections is handled after all sections have been processed, so their order only matter in relation to other StyleguideExtendBefore and StyleguideExtendAfter. They are applied in the provided order. So if you have 3 directories of styles, with directory 2 and directory 3 both adding a StyleguideExtendAfter for the same section, the content from directory 2 is merged in first, and the content from directory 3 is mergen in last.