search

kneath / kss

A methodology for documenting CSS and generating styleguides.
warpspire.com/kss
MIT License
4.04k stars 275 forks source link

Support example html in comments and add API to access to Section #56

Closed mkdynamic closed 11 years ago

mkdynamic commented 11 years ago

Example comment with html:

// A basic button.
//
// :hover    - The hover state
// :active   - The pressed state
// :disabled - The disabled state
//
// <button class="m-btn $modifier-class">Button</button>
//
// Styleguide 1.1

Accessible via Section#example_html.

mkdynamic commented 11 years ago

If there is support for this idea, I can clean up this commit. Some other minor things in here too atm.

mkdynamic commented 11 years ago

Should add that a nice benefit of this, is that you can iterate through style definitions programmatically in the styleguide without having to manually define each one. Something like:

<% Kss::Parser.new('css/path').sections.each do |number, section| %>
  <%= render "section", section: section %>
<% end %>
benschwarz commented 11 years ago

@neonelectro — Looks like we can close this one too, correct?

arielkirkwood commented 11 years ago

@benschwarz Ah, I think you may be confused. GitHub says I've merged a pull request, but this is in my own fork of KSS - since it seems like things aren't moving quickly on this project, I've been merging pull requests I want in my own fork for my projects.

arielkirkwood commented 11 years ago

Do you have commit access, @benschwarz? I'd love to see this PR merged into the master, so I can stop using my own fork :+1:

benschwarz commented 11 years ago

@neonelectro You're right, I was totally confused. I guess I was looking over the issues / prs too quickly. I do have commit access… I'll spend some time reviewing all the outstanding PRs / issues in the next couple of days and come up with a release.

Stay tuned.

benschwarz commented 11 years ago

Can you rebase this and ensure that its ready to merge @mkdynamic? Would love to see this go in.

mkdynamic commented 11 years ago

http://devopsreactions.tumblr.com/post/51955579774/when-you-see-someone-rebasing-already-pushed-changes

benschwarz commented 11 years ago

@mkdynamic I just want this easily mergable without conflicts.

briansloane commented 11 years ago

I would love to see this PR merged as well. @benschwarz, @mkdynamic do you want me to fork this and make a new PR with the conflicts resolved?

jankeesvw commented 11 years ago

I really like this idea!

The hardest part with KSS is maintaining the separate HTML files. It would be great if the HTML code could be included within the comments in the CSS file.

:+1:

mkdynamic commented 11 years ago

Yes please. Sorry, lack of time to address this myself. 

—

Sent from Mailbox for iPhone

On Tue, Aug 20, 2013 at 11:07 AM, Brian Sloane notifications@github.com wrote:

I would love to see this PR merged as well. @benschwarz, @mkdynamic do you want me to fork this and make a new PR with the conflicts resolved?

Reply to this email directly or view it on GitHub: https://github.com/kneath/kss/pull/56#issuecomment-22964777

cgilchrist commented 11 years ago

Would love to see this merged as well!

jankeesvw commented 11 years ago

@briansloane let me know if you need help. Would love to contribute!

kneath commented 11 years ago

I posted this comment over in #77 but I'll re-post here:

Thanks so much for looking into this — I've been letting it sit on my brain for a while (and procrastinating, let's be honest) but now I think I can definitely say I'm :-1: on this. It feels weird, and doesn't really embrace the core of what we're documenting IMO — the CSS. It looks great for a <button> but this is rarely the case for the more typical styleguide use cases. It clutters up the CSS past readability, which is one of the core concerns for KSS for me — easy, accessible, clean documentation.

Take a look around https://github.com/styleguide/css and see how many examples are one line. Let's give a more realistic use case:

// A button suitable for giving stars to someone.
//
// :hover             - Subtle hover highlight.
// .stars-given       - A highlight indicating you've already given a star.
// .stars-given:hover - Subtle hover highlight on top of stars-given styling.
// .disabled          - Dims the button to indicate it cannot be used.
//
// <div class="form-checkbox">
//   <label>
//     <input type="checkbox" checked="checked">
//     Available for hire
//   </label>
//   <p class="note">
//     This will do insanely <strong>awesome</strong> and <strong>amazing</strong> things!
//   </p>
// </div>

// <div class="form-checkbox">
//   <label>
//     <input type="checkbox" checked="checked">
//     <em class="highlight">A far more important option</em>
//   </label>
//   <p class="note">
//     It will surely do something magical.
//   </p>
// </div>
//
// Styleguide 2.1.3.

At the end of the day, I feel like this makes the documentation less useful.