trulia / hologram Goto Github PK
View Code? Open in Web Editor NEWA markdown based documentation system for style guides.
Home Page: http://trulia.github.io/hologram
License: Other
A markdown based documentation system for style guides.
Home Page: http://trulia.github.io/hologram
License: Other
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!
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.
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.
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.
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.
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.
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.
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:
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 ...
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!
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:in
process_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:in
each'
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:in
block 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:in
process_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:in
build_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.
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?
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?
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.
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
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.
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
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 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 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 guide
button guide
Thanks!
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
?
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.
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.
We should give a warning or an error when we find two components with the same name.
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.
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.
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
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.
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)
I would like to create a plugin for generate styleguide with translation (mutli-langual). I need a "hook" or events. Their is somethings available?
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.
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?
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>
If the config file references a directory that does not exist hologram returns an error that the config could not be read.
Here's the todo list:
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 will give transparency into the state of the build.
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?
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.
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>'
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.
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.
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?
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.