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__
Links¶
Check out [http://example.com](The example website).
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.
Markdown format details¶
We use the [Markdown](http://pythonhosted.org/Markdown/) library with the following extensions:
- [sane_lists](http://pythonhosted.org/Markdown/extensions/sane_lists.html)
- [smart_strong](http://pythonhosted.org/Markdown/extensions/smart_strong.html)
- [def_list](http://pythonhosted.org/Markdown/extensions/definition_lists.html)
- [tables](http://pythonhosted.org/Markdown/extensions/tables.html)
- [smarty](http://pythonhosted.org/Markdown/extensions/smarty.html)
- [codehilite](http://pythonhosted.org/Markdown/extensions/code_hilite.html)
- [fenced_code](http://pythonhosted.org/Markdown/extensions/fenced_code_blocks.html)
Each of these extensions have extensive docs if you want to know more.
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.