trulia / hologram Goto Github PK

Hologram do not work on windows. I'm using the Power Shell. Ruby was installed with http://rubyinstaller.org and https://github.com/oneclick/rubyinstaller/wiki/Development-Kit

I do have a hologram config files and it perfectly works on OSX.

PS C:\myProject> hologram
C:/Ruby200/lib/ruby/gems/2.0.0/gems/posix-spawn-0.3.8/lib/posix/
'which' is not recognized as an internal or external command,
operable program or batch file.
(?°?°)?? ???  Build not complete.
 Could not load config file, try 'hologram init' to get started

This repository is publicly accessible. Pushing proprietary code to this repo could reveal trade secrets.

If this is intentional, please contact your lead so this repo can be whitelisted. Until that time, please refrain from pushing code to this repo.

Not sure what the best way to handle this is, but we probably shouldn't expect everyone to nest children in directories below the parent.

Here's the todo list:

• Make sure we're cleared with legal
• Move TruliaMarkdown to a config option
• Add a real readme
• Create an example for building docs
• Create a simple github page
• Solve the problem of parsing more than one comment block
• Add a rakefile
• Basic test coverage?

To generate a complete Navigation for the documentation the _header.html ERB needs access to categories. categories should be a list of each category, that generates an html files. Each item in the should contain the title, file_name and maybe the blocks list as well.

The Navigation section in the hologram example could then be updated accordingly:

<ul class="docNav listInline">
    <% @categories.each do |category| %> 
        <li>
            <a href="#<%= category[:file_name] %>"><%= category[:title] %></a>
        </li>
    <% end %>
</ul>

This repository is publicly accessible. Pushing proprietary code to this repo could reveal trade secrets.

If this is intentional, please contact your lead so this repo can be whitelisted. Until that time, please refrain from pushing code to this repo.

This repository is publicly accessible. Pushing proprietary code to this repo could reveal trade secrets.

If this is intentional, please contact your lead so this repo can be whitelisted. Until that time, please refrain from pushing code to this repo.

Is it really necessary to have rspec as a runtime dependency? I've never written a gem myself, but as I understand it, rspec should go into the Gemfile, so it's available at build time.

Bundler could not find compatible versions for gem "rspec":
  In Gemfile:
    hologram (~> 1.0.1) ruby depends on
      rspec (~> 2.14.1) ruby

    rspec (3.0.0.beta2)

If the config file references a directory that does not exist hologram returns an error that the config could not be read.

1. make the error reporting more accurate and robust
2. should we just create the directory in that case?

I created the folders and yml file as directed, and used the "buttons" doc from the site, and running "hologram" just gives me:

Warning: Could not generate index.html, there was no content generated for the category basics.
Warning: Could not copy dependency: ./build

I have an interest in having a tabbed interface for code in a given example. The reason being is sometimes an example requires multiple code environments for proper implementation. For example, we like to use scss to keep our grids in our stylesheets like so:

// html markup
<header>
   <div class="nav-links">...</div>
   <div class="account-links">...</div>
</header>

// Css markup
header { @include grid-row; }
.nav-links { @include column(6); }
.account-links { @include column(6); }

I would be happy to create a fork and PR if having a tabbed interface is something you guys would consider merging into the code base. Otherwise we will just include both markup in a single code block.

The docs state that an item that defines a parent will be included in its parent's documentation.

This is only true if the child has the same category defined.

To minimize documentation maintenance (that defining a style guide, and not hologram's documentation), does it make sense to have the child inherit the category from its parent?

This is somewhat related to issue #83

The link in the README is pointing to this https://github.com/trulia/hologram-example/tree/gh-pages/hologram_assets/doc_assets/css which is returning a 404.

I cloned the hologram-example repo and ran hologram config.yml then I got this error:

Build not complete.
 Could not parse YAML:
title: Badges
name: badge
category: Components
author:

But if I put a space after author: or if I put a value after it then there's no problem running the command.

We should give a warning or an error when we find two components with the same name.

Just looking at alternatives to KSS which is what I currently use for generating documentation and stumbled across hologram which looks great! A feature I feel it misses (unless I've missed it somewhere) is the ability to create modifiers like KSS, so instead of writing:

<button class="btn">Click</button>
<button class="btn btnAlert">Click</button> 
<button class="btn btnWarning">Click</button> 

KSS allows you to do:

<button class="btn {$modifiers}">Click</button>

.btnAlert - Red button
.btnWarning - Yellow button

Each modified version is then generated as an example in the docs. I find this very handy for showing variations of a component.

Is a similar feature like this available in hologram?

This repository is publicly accessible. Pushing proprietary code to this repo could reveal trade secrets.

If this is intentional, please contact your lead so this repo can be whitelisted. Until that time, please refrain from pushing code to this repo.

Hallo,
since i installed osx mavericks i get the following error message: Maybe sombody know what to do.

/Library/Ruby/Gems/2.0.0/gems/hologram-0.6.0/lib/hologram.rb:216:in `scan': invalid byte sequence in UTF-8 (ArgumentError)
    from /Library/Ruby/Gems/2.0.0/gems/hologram-0.6.0/lib/hologram.rb:216:in `process_file'
    from /Library/Ruby/Gems/2.0.0/gems/hologram-0.6.0/lib/hologram.rb:202:in `block in process_files'
    from /Library/Ruby/Gems/2.0.0/gems/hologram-0.6.0/lib/hologram.rb:198:in `each'
    from /Library/Ruby/Gems/2.0.0/gems/hologram-0.6.0/lib/hologram.rb:198:in `process_files'
    from /Library/Ruby/Gems/2.0.0/gems/hologram-0.6.0/lib/hologram.rb:191:in `block in process_dir'
    from /Library/Ruby/Gems/2.0.0/gems/hologram-0.6.0/lib/hologram.rb:184:in `each'
    from /Library/Ruby/Gems/2.0.0/gems/hologram-0.6.0/lib/hologram.rb:184:in `process_dir'
    from /Library/Ruby/Gems/2.0.0/gems/hologram-0.6.0/lib/hologram.rb:127:in `build_docs'
    from /Library/Ruby/Gems/2.0.0/gems/hologram-0.6.0/lib/hologram.rb:92:in `init'
    from /Library/Ruby/Gems/2.0.0/gems/hologram-0.6.0/bin/hologram:5:in `<top (required)>'
    from /usr/bin/hologram:23:in `load'
    from /usr/bin/hologram:23:in `<main>'

This repository is publicly accessible. Pushing proprietary code to this repo could reveal trade secrets.

If this is intentional, please contact your lead so this repo can be whitelisted. Until that time, please refrain from pushing code to this repo.

Hologram currently only supports multi-line comments. /*
The use of single line comments // should be an option and would also be great providing the ability to omit the style guide code from the generated css.

The last release is from February. It's not very old but you made a lot of cool changes during this time. Do you plan to publish a new gem release?

I try the new feature to build custom erb files, like my doc_data.json for JS search engine, but Hologram didn't compile my file and inside the styleguide dir, I have always the doc_data.json.erb ...

I'd love to be able to nest categories further. ex:

├── elements
│   ├── _forms.sass
│   ├── _lists.sass
│   ├── _loader.sass
│   ├── _tables.sass
│   ├── buttons
│   │   ├── _button.sass
│   │   ├── _close-button.sass
│   │   ├── _minor-button.sass
│   │   └── _save-button.sass
│   ├── forms
│   │   ├── _input-labels.sass
│   │   └── _text-inputs.sass
│   ├── lists
│   │   ├── _bare-list.sass
│   │   ├── _line-list.sass
│   │   ├── _list.sass
│   │   └── _tabs.sass
│   └── text
│       ├── _copy.sass
│       └── _headlines.sass
├── helpers
│   ├── _formatters.sass
│   └── _helpers.sass

that way I can arrange by type, in this case:

• elements
• components
• modules
• helpers

http://kramdown.gettalong.org/index.html

I've been using Middleman for some site generation, and it uses kramdown. Was trying to do some custom handling of image tags, and eventually discovered that kramdown has some very nice extension features that Redcarpet does not. Also, Redcarpet has a few issues that impacted me directly like not recognizing html5 tags yet, and not supporting lists more than 5 levels deep.

Examples:
putting {.class} or {#id} after some markup will add the id or class. Can also use standard Ruby hash syntax to add additional attributes.

kramdown also supports markdown within html blocks (http://kramdown.gettalong.org/syntax.html#html-blocks)

Several other nice features in here, and it appears that it's extensible like Redcarpet.

Obviously this would break everyone's custom renderers, so I thought I'd reach out and see if there's any appetite for this. I may do it regardless just as an exercise in Ruby coding for myself, but if the community wants it too then it's more incentive more me.

Hi!

I'm starting a component library using Hologram as the tool to generate it.

I'm getting this error in my project and can't figure out what's causing it.

Command failed: /Users/vince/.rvm/gems/ruby-1.9.3-p545/gems/hologram-1.0.1/lib/hologram/doc
_builder.rb:200:in `initialize': Is a directory - /Users/vince/Projects/leveleleven/builder-component-library/build/ (Errno::EIS
DIR)

my hologram_config.yml:

# Hologram will run from same directory where this config file resides
# All paths should be relative to there

# The directory containing the source files to parse recursively
source: ./app/styles

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

# The assets needed to build the docs (includes header.html,
# footer.html, etc)
# You may put doc related assets here too: images, css, etc.
documentation_assets: ./app/templates

# Any other asset folders that need to be copied to the destination
# folder. Typically this will include the css that you are trying to
# document. May also include additional folders as needed.
#dependencies:

# Mark which category should be the index page
# Alternatively, you may have an index.md in the documenatation assets
# folder instead of specifying this configu.
#index: basics

Any ideas what I'm doing wrong?

On https://rubygems.org/gems/hologram/versions I see a lot of release number like 1.0.1 where I can't find it back in this repository tags. I'm missing something?

I would like to create a plugin for generate styleguide with translation (mutli-langual). I need a "hook" or events. Their is somethings available?

I cloned the hologram-example then ran hologram config.yml and opened docs/index.html, but the compiled CSS doesn't seem to be linked properly. Not sure if I'm suppose to change the folder structure in any way?

Current folder structure:

Hey guys, is there a way to order objects underneath a parent category? Right now, when I put two components (i.e. buttons.less, grid.less) in the same category it adds them to the styleguide in reverse alphabetical order.

Grid

grid guide

Buttons

button guide

Thanks!

I know this is currently handled by the markdown parser, but the current code examples and samples are technically semantically incorrect. Code examples are outputted in <pre> tags. According to the W3:

In the following snippet, a sample of computer code is presented.

<p>This is the <code>Panel</code> constructor:</p>
<pre><code>function Panel(element, canClose, closeHandler) {
 this.element = element;
 this.canClose = canClose;
 this.closeHandler = function () { if (closeHandler) closeHandler() };
}</code></pre>

This would not only improve semantics, but allow out-of-the-box compatibility with syntax tools like Prism.js

Hey all,
Would love to see badges from code climate and friends on the read me. Its handy, stylish, and all the cool kids are doing it.

http://elgalu.github.io/2013/add-achievement-badges-to-your-gem-readme/

Thoughts?
J

Question. I'm having issues getting Hologram up and running on a Rails 3.2.16 project that uses the traditional SASS syntax. SASS comments like this:

/*doc
  ---
  title: Buttons
  name: button
  category: Forms CSS
  ---

  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-primary">Click</button>
  <a class="btn" href="http://trulia.com">Trulia!</a>
  /```

  Default button style is generic. See:
  http://designweb.blurb.com/patterns/#button-generic
  */

... get converted to

/*doc
 * ---
 * title: Buttons
 * name: button
 * category: Forms CSS
 * ---
 *
 * 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-primary">Click</button>
 * <a class="btn" href="http://trulia.com">Trulia!</a>
 * ```
 *
 * Default button style is generic. See:
 * http://designweb.blurb.com/patterns/#button-generic
 */

Hologram isn't picking these up, I'm assuming b/c of the asterisk preceding each line. Is there a way around this?

Thanks for this great tool!

Hi !

First, I want to say that your tool is really cool. We test so many styleguide generators, but yours seems to be one of the best for our needs.

Anyway, last week I create a nicer theme for Hologram called Cortana and I see something important is missing : the dynamic inclusion of used stylesheet and scripts into the build. In the config file we define the path of all the files which will be parse and use to build the doc, but we have always to include manually all those files in the theme to render our examples.

Can you do something to reuse the source config and dynamically include all the css/js files in the final doc build ?

Something we put together. Sharing the love.

https://github.com/kmayer/guard-hologram

This repository is publicly accessible. Pushing proprietary code to this repo could reveal trade secrets.

If this is intentional, please contact your lead so this repo can be whitelisted. Until that time, please refrain from pushing code to this repo.

Right now if you name your components

apple
Banana
pear

They will alphabetize in the nav and page like so:

Banana
apple
pear

Instead, it would be great if they sorted according to the first example.

Just wondering, since I don't use plain CSS anymore, should I fist compile SASS keeping comments intact and then run through hologram or there is hope of supporting SASS?

I got this error. Certainly because a char than I can write on the disk.

$ hologram
/usr/local/Cellar/ruby/2.1.1/lib/ruby/gems/2.1.0/gems/hologram-1.0.1/lib/hologram/doc_parser.rb:82:in `scan': invalid byte sequence in US-ASCII (ArgumentError)
    from /usr/local/Cellar/ruby/2.1.1/lib/ruby/gems/2.1.0/gems/hologram-1.0.1/lib/hologram/doc_parser.rb:82:in `process_file'
    from /usr/local/Cellar/ruby/2.1.1/lib/ruby/gems/2.1.0/gems/hologram-1.0.1/lib/hologram/doc_parser.rb:69:in `block in process_files'
    from /usr/local/Cellar/ruby/2.1.1/lib/ruby/gems/2.1.0/gems/hologram-1.0.1/lib/hologram/doc_parser.rb:65:in `each'
    from /usr/local/Cellar/ruby/2.1.1/lib/ruby/gems/2.1.0/gems/hologram-1.0.1/lib/hologram/doc_parser.rb:65:in `process_files'
    from /usr/local/Cellar/ruby/2.1.1/lib/ruby/gems/2.1.0/gems/hologram-1.0.1/lib/hologram/doc_parser.rb:59:in `block in process_dir'
    from /usr/local/Cellar/ruby/2.1.1/lib/ruby/gems/2.1.0/gems/hologram-1.0.1/lib/hologram/doc_parser.rb:52:in `each'
    from /usr/local/Cellar/ruby/2.1.1/lib/ruby/gems/2.1.0/gems/hologram-1.0.1/lib/hologram/doc_parser.rb:52:in `process_dir'
    from /usr/local/Cellar/ruby/2.1.1/lib/ruby/gems/2.1.0/gems/hologram-1.0.1/lib/hologram/doc_parser.rb:19:in `parse'
    from /usr/local/Cellar/ruby/2.1.1/lib/ruby/gems/2.1.0/gems/hologram-1.0.1/lib/hologram/doc_builder.rb:72:in `build_docs'
    from /usr/local/Cellar/ruby/2.1.1/lib/ruby/gems/2.1.0/gems/hologram-1.0.1/lib/hologram/doc_builder.rb:38:in `init'
    from /usr/local/Cellar/ruby/2.1.1/lib/ruby/gems/2.1.0/gems/hologram-1.0.1/bin/hologram:5:in `<top (required)>'
    from /usr/local/opt/ruby/bin/hologram:23:in `load'
    from /usr/local/opt/ruby/bin/hologram:23:in `<main>'

Currently we only handle outputting markdown headers for parent and child relationships that are one level deep (# and ##). Remove hard coding of these and make them based off the level of nesting.

Bundler could not find compatible versions for gem "yajl-ruby":
  In Gemfile:
    hologram (>= 0) ruby depends on
      yajl-ruby (~> 1.1.0) ruby

    yajl-ruby (1.2.0)

Bundler could not find compatible versions for gem "sass":
  In Gemfile:
    hologram (>= 0) ruby depends on
      sass (~> 3.2.7) ruby

    compass (= 0.13.alpha.12) ruby depends on
      sass (3.3.2)

Can we update hologram.gemspec?

When I run hologram config.yml I get the following back:

←[32m(?°?°)?←[0m←[31m? ??? ←[0m←[31m Build not complete.←[0m
Failed to get header.

It does actually build a file with the header in there. But not sure what the error is suppose to say before that. Anyone else had this?

I'm running Windows 8

This repository is publicly accessible. Pushing proprietary code to this repo could reveal trade secrets.

If this is intentional, please contact your lead so this repo can be whitelisted. Until that time, please refrain from pushing code to this repo.

This isn't really a bug but I wanted to point out I could only get the sidebar menu to load when I ran the docs from a local server.

I'm guessing this is because of some JS reading the structure, but thought you might want to add this to the docs as I scratched my head a minute before trying it from a local server.

Alternatively, if I'm doing something wrong and my workaround is a red herring - I'd love some help. Thanks!

This repository is publicly accessible. Pushing proprietary code to this repo could reveal trade secrets.

If this is intentional, please contact your lead so this repo can be whitelisted. Until that time, please refrain from pushing code to this repo.

Seems naming a folder *.css in sources results in this error :

/var/lib/gems/1.9.1/gems/hologram-1.0.1/lib/hologram/doc_parser.rb:75:in read': Is a directory - css/inuit.css (Errno::EISDIR) from /var/lib/gems/1.9.1/gems/hologram-1.0.1/lib/hologram/doc_parser.rb:75:inprocess_file'
from /var/lib/gems/1.9.1/gems/hologram-1.0.1/lib/hologram/doc_parser.rb:69:in block in process_files' from /var/lib/gems/1.9.1/gems/hologram-1.0.1/lib/hologram/doc_parser.rb:65:ineach'
from /var/lib/gems/1.9.1/gems/hologram-1.0.1/lib/hologram/doc_parser.rb:65:in process_files' from /var/lib/gems/1.9.1/gems/hologram-1.0.1/lib/hologram/doc_parser.rb:59:inblock in process_dir'
from /var/lib/gems/1.9.1/gems/hologram-1.0.1/lib/hologram/doc_parser.rb:52:in each' from /var/lib/gems/1.9.1/gems/hologram-1.0.1/lib/hologram/doc_parser.rb:52:inprocess_dir'
from /var/lib/gems/1.9.1/gems/hologram-1.0.1/lib/hologram/doc_parser.rb:19:in parse' from /var/lib/gems/1.9.1/gems/hologram-1.0.1/lib/hologram/doc_builder.rb:72:inbuild_docs'
from /var/lib/gems/1.9.1/gems/hologram-1.0.1/lib/hologram/doc_builder.rb:38:in init' from /var/lib/gems/1.9.1/gems/hologram-1.0.1/bin/hologram:5:in<top (required)>'
from /usr/local/bin/hologram:23:in load' from /usr/local/bin/hologram:23:in

Folder structure used : cf. https://github.com/csswizardry/inuit.css/

This repository is publicly accessible. Pushing proprietary code to this repo could reveal trade secrets.

If this is intentional, please contact your lead so this repo can be whitelisted. Until that time, please refrain from pushing code to this repo.

This repository is publicly accessible. Pushing proprietary code to this repo could reveal trade secrets.

If this is intentional, please contact your lead so this repo can be whitelisted. Until that time, please refrain from pushing code to this repo.

In one of my projects I have a vendor folder with some third party javascript. One third party is cookie.js, which is in a file named cookie.js within a folder named cookie.js. It appears that hologram is running into the folder cookie.js and trying to parse it as a file - where it fails with a is directory exception.

Jasmines-iMac:EMRDemo jhegman$ hologram hologram-test-cfg.yml 
/Library/Ruby/Gems/1.8/gems/hologram-0.5.3/lib/hologram.rb:151:in `read': Is a directory - /Users/jhegman/architecture/EMRDemo/public/shared/js/framework/vendor//cookie.js (Errno::EISDIR)
    from /Library/Ruby/Gems/1.8/gems/hologram-0.5.3/lib/hologram.rb:151:in `process_file'
    from /Library/Ruby/Gems/1.8/gems/hologram-0.5.3/lib/hologram.rb:144:in `process_files'
    from /Library/Ruby/Gems/1.8/gems/hologram-0.5.3/lib/hologram.rb:140:in `each'
    from /Library/Ruby/Gems/1.8/gems/hologram-0.5.3/lib/hologram.rb:140:in `process_files'
    from /Library/Ruby/Gems/1.8/gems/hologram-0.5.3/lib/hologram.rb:134:in `process_dir'
    from /Library/Ruby/Gems/1.8/gems/hologram-0.5.3/lib/hologram.rb:127:in `each'
    from /Library/Ruby/Gems/1.8/gems/hologram-0.5.3/lib/hologram.rb:127:in `process_dir'
    from /Library/Ruby/Gems/1.8/gems/hologram-0.5.3/lib/hologram.rb:97:in `build_docs'
    from /Library/Ruby/Gems/1.8/gems/hologram-0.5.3/lib/hologram.rb:76:in `init'
    from /Library/Ruby/Gems/1.8/gems/hologram-0.5.3/bin/hologram:5
    from /usr/bin/hologram:19:in `load'
    from /usr/bin/hologram:19

I can rename the directory to anything not ending in .js and things compile fine.

So summary is that folders ending with ".js" break hologram's build process.

I imagine using Hologram in addition to my normal Compass or SassC compiling, not in place of it.

To do this without getting errors, you need to use Sass's multi-line comments "//". but the docs only have single line: "/*".

I'm sure future developers would appreciate that in the docs, it's a bit of a nuance.

This will give transparency into the state of the build.