Skip to content
This repository has been archived by the owner on Aug 27, 2019. It is now read-only.

Latest commit

 

History

History
215 lines (155 loc) · 9.72 KB

README.md

File metadata and controls

215 lines (155 loc) · 9.72 KB
Raw

a-pollo

Version TravisCI Built with nodejs 4.2.2 NPM Built with hexo 3.2.0 MIT licence

A-pollo generates CSS style guide documentation from your code comments.

It's been written for teams who need to check CSS widgets with examples, copy html related code with no pain to go through browser HTML debugger.

Release notes

  • Documentation annotations support
  • Remove use_markdown var from config
  • Add data-style snippet attribute to ease snippet specific examples
  • Change named widgets to snippets
  • Update snippet style
  • Add new font icons

a-pollo preview

Roadmap

  • Default style guide articles for CSS
  • Default style guide articles for HTML
  • Single widget tests with CSSlint
  • Single widget StyleStats report
  • Documentation tags for SASS
  • Documentation tags for LESS

The module works with Hexo, an easy to use and powerful blog framework, so if you'd like to write your own theme you'll have the power this nice tool in your fingers.

To install a-pollo in your project

npm install --save a-pollo

To create a config file

From package.json where you have installed node_modules folder

./node_modules/.bin/a-pollo init

It will start a process will help you to build the first one.

To run a-pollo

From package.json where you have installed node_modules folder

./node_modules/.bin/a-pollo

Doc style guide example

This will be placed on style.docs files defined in the YAML configuration.

/*@pollo
    @name:  Icon
    @icon:  fa-star
    @auth:  [Vittorio Vittori](http://vit.to)
    @category:  Icons
    @date:  2016-01-11
    @text:  This is an icons set composet by an SVG sprite, the single icon is `48px` size.
    @html:  <i class="icon icon--head"></i>
*/

Place a a-pollo.yml in the root folder of your project, this is the default config:

title: 'Client project'                                           # [required] Will be listened on head's title tag
client: '[Client name](http://github.com/vitto/a-pollo#readme)'
developers: '[Vittorio Vittori](http://vit.to), [Pietro Campagnano](https://twitter.com/fain182)'     # [required] Who's managing the style guide
designers: '[Vittorio Vittori](http://vit.to)'      # [required] Who's desining the style guide
date: 2015-11-01                 # [required] When the style guide project was started
date_format: dddd D MMMM YYYY    # [optional] Default from hexo config YYYY-MM-DD

public_dir: ./public        # [required] Where the style guide will be genarated
url: http://localhost:7777  # [optional] HTTP server URL
pages: example_source/a-pollo/*       # [optional] Additional static documentation pages you want to add, (markdown or html)
http_server: true           # [optional] HTTP server with port number
use_markdown: true          # [optional] This will be removed soon, it's used for development
theme: a-pollo              # [optional] The a-pollo theme folder

libs:
    bower: bower.json   # [optional] Link the bower.json file to display Bower used libraries in the index page
    node: package.json  # [optional] Link the package.json file to display NodeJS used libraries in the index page

style:
    docs: example_source/frontsize/themes/default/widgets/        # [required] Where a-pollo comments and tags are placed
    css: example_source/frontsize/test/frontsize-theme.min.css    # [required] This is the CSS will be loaded by a-pollo to show rendered widgets
    images: example_source/frontsize/themes/default/img/*         # [optional] Where the CSS images are stored
    fonts: example_source/frontsize/themes/default/fonts/*        # [optional] Where the CSS fonts are stored

header:
    logo: a-pollo-logo--gold.svg # [optional] The logo image you'll se on every page, it must be stored in style.images
    link: / # [optional] The link on the logo image
    description: A-POLLO / The visual CSS style guide for teams    # [optional] A description under the logo image

footer:
    logo: a-pollo-logo.svg # [optional] The logo image you'll se on every page, it must be stored in style.images
    link: http://vitto.github.io/a-pollo/  # [optional] The link on the logo image
    description: A-POLLO / The visual CSS style guide for teams # [optional] A description under the logo image

Configuration

Property Hexo's shared config Description
title yes Will be shown on HTML page title
author yes Will be shown around the pages
date yes Not yet used
public_dir yes The target path the site will be generated
url yes HTTP server URL
theme yes Theme folder name, you can write your own theme
pages no The customized markdown pages will be published from Hexo
http_server no If the generated guide will be served by the HTTP server
use_markdown no Which method will be used to render the HTML template pages
style.docs no The path where the documentation files are
style.css no The path where the CSS for the documentation is, this is not the CSS of the a-pollo theme
style.images no Image assets for the CSS you are using
style.fonts no Fonts assets for the CSS you are using
header.logo no An image inside style.images to be used as image header inside a-pollo theme
header.description no The header description inside a-pollo theme
header.link no The header logo href link
footer.logo no An image inside style.images to be used as image footer inside a-pollo theme
footer.description no The footer description inside a-pollo theme
footer.link no The footer logo href link
libs.bower no Location of the bower.json file to display Bower used libraries in the index page
libs.node no Location of the package.json file to display NodeJS used libraries in the index page

Development utils

Prepare environment

npm install && ./node_modules/.bin/bower install && cd test && npm install && ./node_modules/.bin/bower install

To build theme

./node_modules/.bin/gulp -s

Generate test CSS

./node_modules/.bin/gulp -s && cd ./test && ./node_modules/.bin/gulp frontsize:css && ../ && node index.js --config a-pollo.test.yml

Generate website example CSS

./node_modules/.bin/gulp -s && cd ./test && ./node_modules/.bin/gulp frontsize:css && ../ && node index.js --config a-pollo.example.yml

To test the HTML results

./node_modules/.bin/gulp -s && node index.js
./node_modules/.bin/gulp -s && node index.js --config a-pollo.test.yml
./node_modules/.bin/gulp -s && node index.js --config a-pollo.example.yml

Generate website

./node_modules/.bin/gulp -s && cd ./hexo && ../node_modules/.bin/hexo --config _site_config.yml generate && cd ../ && php -S localhost:8000 -t ./_site

Coded with love by Vittorio Vittori and Pietro Campagnano @ ideato srl