Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

Add contributors section, format readme #81

Merged
merged 1 commit into from

5 participants

@jdcantrell
Owner

I added a contributors section as a very small way of saying thanks for contributing to hologram.

Please let me know if you'd like to be removed or if you want your name/link to be different. (The relevant diff is at the bottom, sorry for all the formatting changes)

Thanks again for help!

@jho406
@elanakoren
@kmayer
@ostinelli
@stubbornella
@BrentWheeldon

@BrentWheeldon

Thanks, @jdcantrell, but I think you can remove me. The PR that has my name on it appears to have been using the wrong git authors when it was sent, so I'd hate to take credit for something I had no involvement in.

@stubbornella
@kmayer

That's a whole bunch o' pivots in there :+1:

@jho406

:+1: Neat! Thanks @jdcantrell

@jdcantrell
Owner

PR Updated, thanks for the help!

@jdcantrell jdcantrell merged commit 2358062 into trulia:master
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on Apr 29, 2014
  1. Add contributors section, format readme

    JD Cantrell authored
This page is out of date. Refresh to see the latest.
Showing with 134 additions and 71 deletions.
  1. +134 −71 README.md
View
205 README.md
@@ -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
@@ -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
@@ -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
@@ -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
---
@@ -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
@@ -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
@@ -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
@@ -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)
Something went wrong with that request. Please try again.