Generate CSS/SASS/LESS documentation with previews using Markdown in comments.
Project description
# Vitalstyles
Makes it easy to document you LESS/SASS/CSS. You document your styles by inserting markdown with a few extensions to markup examples.
## Goals
Make it easier to document and develop styles.
## Features
- Document your styles with Markdown.
- Create live previews:
- Inline in the guide for simple examples.
- Covering the full width of the guide page for more complex examples.
- Rendered in a full width IFRAME for really complex examples. These examples can also be opened in a separate file.
## Install
```
$ pip install vitalstyles
```
## How it works
You write your css/less/sass like you have always done, but you add markdown in special comments:
``` css
/**
# Buttons
## .fancybutton
A fancy button
$$$
<button class="fancy-button">Click me</button>
$$$
*/
.fancy-button {
}
```
The ``vitalstyles-cli`` can be executed from the directory containing the file with these styles, and it will create a style guide in ``vitalstyles_styleguide/``. By default it will search the current directory recursively for ``*.less``, ``*.sass``, ``*.scss`` and ``*.css`` files.
## Configuration
You can configure vitalstyles through a ``vitalstyles.json`` file. This is the default setting file with defaults:
``` javascript
{
// Path to your CSS file relative to this settings file (or CWD if no settings file).
// You have to set this to get previews.
"preview_cssfile": null,
// The output directory relative to the settings file (or CWD if no settings file).
"outdir": "vitalstyles_styleguide",
// A list of files or directories to parse.
// Directories is searched recursively for ``.scss``,
// ``.sass``, ``.css`` and ``.less`` files.
"inpaths": [],
// User defined templates directory. You can override any
// templates in the ``vitalstyles/templates/`` directory
// (in the repo) by putting them in a directory and specifying
// the directory here. The path is relative to this settings file.
"template_dir": null,
// The title of the guide
"title": "Vitalstyles style guide",
// Include stock assets? This will add a directory named
// stock to your assets/ directory, and fill it with assets
// that you can use in your styleguide.
'include_stock_assets': false,
// A list of filesystem directories. The contents of these directories
// are copied into the assets sub-directory of the ``outdir``.
// The directory itself is not copied, so if you specify two directories
// containing the same file, the file from the last directory in the
// list will overwrite the first.
'asset_directories': []
}
```
## Embedded previews in the docs
If you want to get previews, you have to configure ``preview_cssfile`` in a ``vitalstyles.json``.
## Bundled stock images
We bundle a set of stock images. The bundled stock images are from https://unsplash.com/ and http://www.gratisography.com/.
To use the bundled stock images, you simply set the ``include_stock_assets`` setting to ``true``. This will copy the images from ``vitalstyles/sock_assets/stock/`` (in the sources of this library) into the ``assets/stock/`` subdirectory of the directory specified in the ``outdir`` setting.
## Adding assets (images, videos, etc)
If using the bundled stock images is not enough, you can include one or more asset directories using the ``asset_directories`` setting. You simply add the path to the directories you want to copy into the ``assets/`` subdirectory of the directory specified in the ``outdir`` setting.
## Specifying settings using Python or making a custom CLI
If configuring the styleguide using JSON is not enough, you can make a custom CLI script. This is fairly simple, and it is demonstrated in ``examples/custom_vitalstyles_cli.py``.
## Complete example
See the ``examples/`` directory in the source repo. To build the example, install Vitalstyles and GruntJS and run the following::
$ cd examples/
$ npm install
$ grunt
Then open ``vitalstyles_styleguide/index.html``.
## Markdown dialect
The Markdown dialect is more or less the same as the GitHub format, with one additional tag to markup examples.
The Markdown parser is [python-markdown](https://pythonhosted.org/Markdown/), with the following [extensions](https://pythonhosted.org/Markdown/extensions/index.html):
### Fenced code blocks
Makes it possible to use github markdown styled code blocks like:
``` javascript
function add(a, b) {
return a + b;
}
```
### Smart strong and smart emphasis
Prevents markdown from emphasizing words when you use ``_`` and ``__`` in the middle of a word.
### Definition Lists
Makes it possible to define definition lists with the following markup:
```
Option one
: This is not a very good option. You should consider
using _option two_.
Option two
: This is a really good option.
```
### Tables
Makes it possible to create tables with the following markup:
```
First Header | Second Header
------------- | -------------
Content Cell | Content Cell
Content Cell | Content Cell
```
### SmartyPants
Converts ASCII dashes, quotes and ellipses to their HTML entity equivalents
### Sane lists
Renders lists in a saner manner than the original Markdown.
Makes it easy to document you LESS/SASS/CSS. You document your styles by inserting markdown with a few extensions to markup examples.
## Goals
Make it easier to document and develop styles.
## Features
- Document your styles with Markdown.
- Create live previews:
- Inline in the guide for simple examples.
- Covering the full width of the guide page for more complex examples.
- Rendered in a full width IFRAME for really complex examples. These examples can also be opened in a separate file.
## Install
```
$ pip install vitalstyles
```
## How it works
You write your css/less/sass like you have always done, but you add markdown in special comments:
``` css
/**
# Buttons
## .fancybutton
A fancy button
$$$
<button class="fancy-button">Click me</button>
$$$
*/
.fancy-button {
}
```
The ``vitalstyles-cli`` can be executed from the directory containing the file with these styles, and it will create a style guide in ``vitalstyles_styleguide/``. By default it will search the current directory recursively for ``*.less``, ``*.sass``, ``*.scss`` and ``*.css`` files.
## Configuration
You can configure vitalstyles through a ``vitalstyles.json`` file. This is the default setting file with defaults:
``` javascript
{
// Path to your CSS file relative to this settings file (or CWD if no settings file).
// You have to set this to get previews.
"preview_cssfile": null,
// The output directory relative to the settings file (or CWD if no settings file).
"outdir": "vitalstyles_styleguide",
// A list of files or directories to parse.
// Directories is searched recursively for ``.scss``,
// ``.sass``, ``.css`` and ``.less`` files.
"inpaths": [],
// User defined templates directory. You can override any
// templates in the ``vitalstyles/templates/`` directory
// (in the repo) by putting them in a directory and specifying
// the directory here. The path is relative to this settings file.
"template_dir": null,
// The title of the guide
"title": "Vitalstyles style guide",
// Include stock assets? This will add a directory named
// stock to your assets/ directory, and fill it with assets
// that you can use in your styleguide.
'include_stock_assets': false,
// A list of filesystem directories. The contents of these directories
// are copied into the assets sub-directory of the ``outdir``.
// The directory itself is not copied, so if you specify two directories
// containing the same file, the file from the last directory in the
// list will overwrite the first.
'asset_directories': []
}
```
## Embedded previews in the docs
If you want to get previews, you have to configure ``preview_cssfile`` in a ``vitalstyles.json``.
## Bundled stock images
We bundle a set of stock images. The bundled stock images are from https://unsplash.com/ and http://www.gratisography.com/.
To use the bundled stock images, you simply set the ``include_stock_assets`` setting to ``true``. This will copy the images from ``vitalstyles/sock_assets/stock/`` (in the sources of this library) into the ``assets/stock/`` subdirectory of the directory specified in the ``outdir`` setting.
## Adding assets (images, videos, etc)
If using the bundled stock images is not enough, you can include one or more asset directories using the ``asset_directories`` setting. You simply add the path to the directories you want to copy into the ``assets/`` subdirectory of the directory specified in the ``outdir`` setting.
## Specifying settings using Python or making a custom CLI
If configuring the styleguide using JSON is not enough, you can make a custom CLI script. This is fairly simple, and it is demonstrated in ``examples/custom_vitalstyles_cli.py``.
## Complete example
See the ``examples/`` directory in the source repo. To build the example, install Vitalstyles and GruntJS and run the following::
$ cd examples/
$ npm install
$ grunt
Then open ``vitalstyles_styleguide/index.html``.
## Markdown dialect
The Markdown dialect is more or less the same as the GitHub format, with one additional tag to markup examples.
The Markdown parser is [python-markdown](https://pythonhosted.org/Markdown/), with the following [extensions](https://pythonhosted.org/Markdown/extensions/index.html):
### Fenced code blocks
Makes it possible to use github markdown styled code blocks like:
``` javascript
function add(a, b) {
return a + b;
}
```
### Smart strong and smart emphasis
Prevents markdown from emphasizing words when you use ``_`` and ``__`` in the middle of a word.
### Definition Lists
Makes it possible to define definition lists with the following markup:
```
Option one
: This is not a very good option. You should consider
using _option two_.
Option two
: This is a really good option.
```
### Tables
Makes it possible to create tables with the following markup:
```
First Header | Second Header
------------- | -------------
Content Cell | Content Cell
Content Cell | Content Cell
```
### SmartyPants
Converts ASCII dashes, quotes and ellipses to their HTML entity equivalents
### Sane lists
Renders lists in a saner manner than the original Markdown.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Filename, size | File type | Python version | Upload date | Hashes |
---|---|---|---|---|
Filename, size vitalstyles-1.1.4.tar.gz (432.1 kB) | File type Source | Python version None | Upload date | Hashes View |