Style guide

[jensljungblad]

This PR explores adding a style guide.

• [x] Merge #9 and rebase
• [x] Ability to render markdown files
• [x] Ability to render markdown files with erb
• [x] Page route
• [x] Add page navigation
• [x] Add a way to render examples
  • [x] Print the rendered component in an iframe
  • [x] Print the code for rendering the component with syntax highlighting
  • [x] Make the iframe the correct size for the component. The width should be 100% and the height should have a maximum height, but otherwise adjust based on the height of the content. For components that are 100% wide themselves, it would be useful to be able to pass a width to the example.
• [x] Make a home page for the style guide
• [x] Make the component generator generate a style guide page
• [x] Make an install generator to set up the style guide
• [x] Decide what should be generated by default
• [x] Make it pretty
• [x] There's an issue with including component css, only the first component gets included
• [x] There seems to be an issue with the height of the iframe getting set to 150 even for small components
• [x] There seems to be an issue with JS not being executed in the iframe.. Need to set up a test case for this one
• [x] After changing the way examples are rendered, they now expect an example layout to be defined. This should be generated on install. Is it possible to move the styleguide to app/styleguide?
• [x] The component generator must place the documentation in the right place

There are currently issues with both redcarpet and rouge, with them spitting out a lot of warnings. Hopefully new releases of both gems will fix those. There are also alternatives such as kramdown and coderay available.

Original idea

When it comes to printing the code for rendering the component, my current idea is to do something like this: ```ruby class ExampleComponent has_many :examples do attribute :source end # override this method... def examples(value = nil, attributes = nil, &block) if block # i suppose this will be the value variable in fact, but still... attributes[:source] = block.source # capture the content of the block somehow... end super end end ``` Might need a gem to get the source of the block: https://github.com/banister/method_source. It's possible to do with `#source_location` as well but that means parsing the file, which seems a bit silly. Yet another solution would be to pass it as a string or something and then eval it but that sounds like a worse solution! **Update**: Unfortunately the gems available can't extract the source of an `erb` block, only pure Ruby blocks.. Another issue is that you can't print `erb` markdown blocks without them getting evaluated.

---

The way examples are implemented is through markdown, similar to https://www.catalog.style. That is:

# Alert

Provide contextual feedback messages for typical user actions with the handful of available and flexible alert messages.

```example
<%= component "alert", message: "Something went right!", context: "success" %>

<%= component "alert", message: "Something went wrong!", context: "danger" %>

That would a) render the component and b) render the `erb` source code. In order to do this, I think reversing the processing order should do the trick. That is, first process the template using markdown, then erb.

To test this PR, check out the repo, run `bin/rails server` and navigate to `http://localhost:3000/styleguide`.

[jensljungblad]

@jimmynordlund Cool! I pushed some more markdown examples, I think one additional subheader and a blockquote. They're all on the style guide home page now. Some other feedback:

1. Should there be a max width for the page, or perhaps at least for the example wrapper? They get really wide on a big screen.
2. I think the iframe should be left adjusted instead of centered, for the same reason. It looks a bit weird on a big monitor, and ends up far away from the code sample.
3. The navigation should support at least one more level, but preferably more. Is it possible to redo it and have that work even without sass? Do you think it should be more clear what is clickable and what is not? I added another level to the test guide so should be easy to see it now at least.
4. I don't know about this for sure, but maybe the style guide should go in gray scale, so as not to interfere with the colors of the components? If there was a component with almost the same color as the navigation perhaps that would be annoying :P

(Would prefer not to add sass if possible)

[jimmynordlund]

@jensljungblad Pushed some updated styling with a new, more muted colour scheme and and a nav that supports deeper nesting and clearly differentiates between what’s clickable and what’s not. There’s also a max-width on the main container now. Feels much better.

The only thing I’m not entirely sold on is the left alignment of the component preview in the iframe. I like it centred. I feel like the “misalignment” is a plus, that it’s its own thing, a preview of something that lives somewhere else and therefore should break the “flow” and just be aligned against its own container. It’s also not as jarring now that the max-width of the main container is capped. But, all in all, minor detail. I’m fine with either really.

[jensljungblad]

@jimmynordlund Cool! Feels better with the max width, agreed. I fixed an issue with how the example code was being generated that made the padding a bit weird, and also added a markdown code example to the dummy home page. I tweaked some paddings and stuff in the css, and also moved the font declarations from the pre to the code tag, didn't seem to work on the pre.

I also changed my mind about the Google Font dependency for now :P I have to think a bit if it's a good idea or not.. I added the native-stack from Bootstrap instead for now.

Perhaps it's good enough to test with the real style guide now, and then we can make further tweaks once we see how that looks!