Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add contributors section, format readme #81

Merged
merged 1 commit into from Apr 29, 2014
Merged

Add contributors section, format readme #81

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
205 changes: 134 additions & 71 deletions README.md
View file
Open in desktop
@@ -1,13 +1,23 @@
# Hologram [![Build Status](https://travis-ci.org/trulia/hologram.png)](https://travis-ci.org/trulia/hologram) [![Code Climate](https://codeclimate.com/github/trulia/hologram.png)](https://codeclimate.com/github/trulia/hologram)
# Hologram
[![Build Status](https://travis-ci.org/trulia/hologram.png)](https://travis-ci.org/trulia/hologram)
[![Code Climate](https://codeclimate.com/github/trulia/hologram.png)](https://codeclimate.com/github/trulia/hologram)

Hologram is a Ruby gem that parses comments in your CSS and helps you turn them into a beautiful style guide.
Hologram is a Ruby gem that parses comments in your CSS and helps you
turn them into a beautiful style guide.

There are two steps to building a great style guide:

1. Documenting your css and generating html examples.
2. Styling the output of step 1.

The hologram gem itself is only concerned with step 1. This means you are free to make your style guide look however you would like. If you don't feel like going through this process yourself you can take a look at the [templates](https://github.com/trulia/hologram-example/tree/master/templates) in our [example repository](https://github.com/trulia/hologram-example) and use the assets defined there instead.
The hologram gem itself is only concerned with step 1. This means you
are free to make your style guide look however you would like. If you
don't feel like going through this process yourself you can take a look
at the
[templates](https://github.com/trulia/hologram-example/tree/master/templates)
in our [example repository](https://github.com/trulia/hologram-example)
and use the assets defined there instead.


## Installation

Expand All @@ -21,21 +31,19 @@ And then execute:

If you don't use bundler you can run `gem install hologram`.

##Quick Start

```
hologram init
```
## Quick Start

``` hologram init ```

This will create a `hologram_config.yml` file (more on this below), and also create a starter
`_header.html` and `_footer.html` file for you. You can then tweak the
config values and start documenting your css.
This will create a `hologram_config.yml` file (more on this below), and
also create a starter `_header.html` and `_footer.html` file for you.
You can then tweak the config values and start documenting your css.

Building the documentation is simply:

```
hologram
```
``` hologram ```


## Details

Expand All @@ -49,17 +57,18 @@ There are two things you need to do to start using hologram:
### Creating a YAML config file

Hologram needs a few configuration settings before it can begin to build
your documentation for you. Once this is set up you can execute hologram by
simply running:
your documentation for you. Once this is set up you can execute hologram
by simply running:

`hologram path/to/your/config.yml` or (using bundler) `bundle exec hologram path/to/your/config.yml`
`hologram path/to/your/config.yml` or (using bundler) `bundle exec
hologram path/to/your/config.yml`

Your config file needs to contain the following key/value pairs

* **source**: relative path to your source files

* **destination**: relative path to where you want the documentation to be
built to
* **destination**: relative path to where you want the documentation to
be built to

* **documentation_assets**: The path that contains supporting assets for
the documentaiton page. This typically includes html fragments
Expand All @@ -68,56 +77,61 @@ Your config file needs to contain the following key/value pairs
`_footer.html`, these are used to start and end every html page
hologram generates.

Hologram treats `_header.html` and `_footer.html`
as ERB files for each page that is generated. You can access the
`title`, `file_name`, `blocks`, and `categories`.
Hologram treats `_header.html` and `_footer.html` as ERB files for
each page that is generated. You can access the `title`, `file_name`,
`blocks`, and `categories`.

`blocks` is a list of each documenation block on the page. Each item in the list has a `title`,
`name`, `category`, and optionally a `parent`. This is useful for,
say, building a menu that lists each component.
`blocks` is a list of each documenation block on the page. Each item
in the list has a `title`, `name`, `category`, and optionally a
`parent`. This is useful for, say, building a menu that lists each
component.

`categories` is a list of all the categories found in the documentation
`categories` is a list of all the categories found in the
documentation

**Nota Bene:** Filenames that begin with underscores will not be copied into the destination folder.
**Nota Bene:** Filenames that begin with underscores will not be
copied into the destination folder.


* **custom_markdown**: (optional) this is the filename of a class that
extends RedCarpet::Render::HTML class. Use this for when you need
additional classes or html tags for different parts of the page.
See `example_markdown_renderer.rb.example` for an example of how your class should look like.
additional classes or html tags for different parts of the page. See
`example_markdown_renderer.rb.example` for an example of how your
class can look like.

* **index**: (optional) this is a category (see **Documenting your styles** section below) that will be used as the
index.html.
* **index**: (optional) this is a category (see **Documenting your
styles** section below) that will be used as the index.html.

* **dependencies**: a **list** of relative paths to folders containing
any dependencies your style guide has. These folders will be copied
over into the documentation output directory. PUT THE CSS/JS THAT IS
ACTUALLY BEING DOCUMENTED HERE


##### Example config file

# The directory containing the source files to parse
source: ../components
# The directory containing the source files to parse source:
../components

# The directory that hologram will build to
destination: ../docs
# The directory that hologram will build to destination: ../docs

# The assets needed to build/style the docs (includes header.html, footer.html, etc)
documentation_assets: ../hologram_assets
# The assets needed to build/style the docs (includes header.html,
footer.html, etc) documentation_assets: ../hologram_assets

# A custom markdown renderer that extends `RedCarpet::Render::HTML class`
custom_markdown: trulia_markdown_renderer.rb
# A custom markdown renderer that extends `RedCarpet::Render::HTML
class` custom_markdown: trulia_markdown_renderer.rb

# Any other asset folders that need to be copied to the destination folder
# This is where the CSS/JS you are actually documenting should go
dependencies:
# Any other asset folders that need to be copied to the destination
folder # This is where the CSS/JS you are actually documenting
should go dependencies:
- ../build


###Documenting your styles
### Documenting your styles

Hologram will scan for stylesheets (.css, .scss, .sass, .less, or .styl) within the **source** directory defined in you configuraiton.
It will look for comments that match the following:
Hologram will scan for stylesheets (.css, .scss, .sass, .less, or .styl)
within the **source** directory defined in you configuraiton. It will
look for comments that match the following:

/*doc
---
Expand All @@ -129,10 +143,8 @@ It will look for comments that match the following:
Button styles can be applied to any element. Typically you'll want
to use either a `<button>` or an `<a>` element:

```html_example
<button class="btn btnDefault">Click</button>
<a class="btn btnDefault" href="trulia.com">Trulia!</a>
```
```html_example <button class="btn btnDefault">Click</button> <a
class="btn btnDefault" href="trulia.com">Trulia!</a> ```

If your button is actually a link to another page, please use the
`<a>` element, while if your button performs an action, such as
Expand All @@ -142,42 +154,68 @@ It will look for comments that match the following:
*/

The first section of the comment is a yaml block that defines certain
aspects of the this documentation block (more on that in the next section). The second part is simply
markdown as defined by Redcarpet.
aspects of the this documentation block (more on that in the next
section). The second part is simply markdown as defined by Redcarpet.

Notice the use of `html_example`. This tells the markdown renderer that
it should treat the example as...well...html. If your project uses
[haml](http://haml.info/) you can also use `haml_example`. In that case
the output will be html for the example and the code block will show the
haml used to generate the html. For components that require
[javascript](https://www.destroyallsoftware.com/talks/wat) you can use
`js_example` for your javascript. In addition to outputing the
javascript in a `<code>` block it will also wrap it in a `<script>` tag
for execution.


Notice the use of `html_example`. This tells the markdown renderer that it should treat the example as...well...html. If your project uses [haml](http://haml.info/) you can also use `haml_example`. In that case the output will be html for the example and the code block will show the haml used to generate the html. For components that require [javascript](https://www.destroyallsoftware.com/talks/wat) you can use `js_example` for your javascript. In addition to outputing the javascript in a `<code>` block it will also wrap it in a `<script>` tag for execution.
#### Document YAML section

####Document YAML section
The yaml in the documention block can have any key value pair you deem important
but it specifically looks for the following keys:
The yaml in the documention block can have any
key value pair you deem important but it specifically looks for the
following keys:

* **title**: The title to display in the documents
* **category**: This is the broad category for the component, all
components in the same category will be written to the same page.
* **name**: This is used for grouping components, by assigning
a name a component can be referenced in another component as a parent.
* **parent**: (Optional.) This should be the **name** of another components. If this is set the current component will be displayed as a section within the **parent**'s documentation.
* **name**: This is used for grouping components, by assigning a name a
component can be referenced in another component as a parent.
* **parent**: (Optional.) This should be the **name** of another
components. If this is set the current component will be displayed as
a section within the **parent**'s documentation.

For example, you might have a component with the **name** *buttons* and another component named *buttonSkins*. You could set the **parent** for the *buttonSkins* component to be *buttons*. It would then nest the *buttonSkins* documentation inside the *buttons* documentation.
For example, you might have a component with the **name** *buttons* and
another component named *buttonSkins*. You could set the **parent** for
the *buttonSkins* component to be *buttons*. It would then nest the
*buttonSkins* documentation inside the *buttons* documentation.

Each level of nesting (components are infinitely nestable) will have a heading tag that represents its depth. In the above example *buttons* would have an `<h1>` and *buttonSkins* would have an `<h2>`. This you can [see this exact example in our demo repo](https://github.com/trulia/hologram-example/tree/master/components/button), and the output of this nesting [in our demo styleguide](http://trulia.github.io/hologram-example/base_css.html#Buttons).
Each level of nesting (components are infinitely nestable) will have a
heading tag that represents its depth. In the above example *buttons*
would have an `<h1>` and *buttonSkins* would have an `<h2>`. This you
can [see this exact example in our demo
repo](https://github.com/trulia/hologram-example/tree/master/components/button),
and the output of this nesting [in our demo
styleguide](http://trulia.github.io/hologram-example/base_css.html#Buttons).


###Documentation Assets
### Documentation Assets

The documentation assets folder contains the html, css, js and images
you'll need for making your style guide look beautiful.

Hologram doesn't care too much about to what is in here as it is intended
to be custom for your style guide.
Hologram doesn't care too much about to what is in here as it is
intended to be custom for your style guide.

#####Styling Your Code Examples

Hologram uses [pygments.rb](https://github.com/tmm1/pygments.rb) gem to provide
syntax highlighting for code examples. One of the assets that you probably want
to include in your documentation assets folder is a css file that styles the
"pygmentized" code examples. We use `github.css` which can be found along with the
css we use to style code blocks [here](https://github.com/trulia/hologram-example/tree/gh-pages/hologram_assets/doc_assets/css).
##### Styling Your Code Examples

Hologram uses [pygments.rb](https://github.com/tmm1/pygments.rb) gem to
provide syntax highlighting for code examples. One of the assets that
you probably want to include in your documentation assets folder is a
css file that styles the "pygmentized" code examples. We use
`github.css` which can be found along with the css we use to style code
blocks
[here](https://github.com/trulia/hologram-example/tree/gh-pages/hologram_assets/doc_assets/css).


## Supported Preprocessors/File Types

Expand All @@ -189,8 +227,13 @@ The following preprocessors/file types are supported by Hologram:
- Javascript (.js)
- Markdown (.md, .markdown)


## Extensions and Plugins
- [Guard Hologram](https://github.com/kmayer/guard-hologram) is a sweet little gem that uses guard to monitor changes to your hologram project and rebuilds your styleguide on the fly as you make changes.

- [Guard Hologram](https://github.com/kmayer/guard-hologram) is a sweet
little gem that uses guard to monitor changes to your hologram project
and rebuilds your styleguide on the fly as you make changes.


## Contributing

Expand All @@ -201,7 +244,27 @@ The following preprocessors/file types are supported by Hologram:
5. Create new Pull Request


## License
[Hologram is licensed under the MIT License](https://github.com/trulia/hologram/blob/master/LICENSE.txt)
## Authors

Hologram is written and maintained by [August
Flanagan](http://github.com/aflanagan) and [JD
Cantrell](http://github.com/jdcantrell).


## Contributors

These fine people have also contributed to making hologram a better gem:

* [Rajan Agaskar](https://github.com/ragaskar)
* Louis Bennett
* [jho406](https://github.com/jho406)
* johny (wrote our initial tests!)
* [Elana Koren](https://github.com/elanakoren)
* [Ken Mayer](https://github.com/kmayer)
* [Roberto Ostinelli](https://github.com/ostinelli)
* [Nicole Sullivan](https://github.com/stubbornella)


## License

[Hologram is licensed under the MIT License](https://github.com/trulia/hologram/blob/master/LICENSE.txt)