documented-style-sheets / parser Goto Github PK

The readme and documentation hasn't been kept up-to-date with some changes that have been made. There needs to be a more concerted effort to keep that continuously synced with any kind of API changes. The more documentation, images, videos and resources, in general, we can provide, the better traction this library will have.

I would like to get a bit more control over which elements in the markup recieve the state values. This would help when building up elements of more than just a single element. and ensure the state value is applied exactly where I want. It would also help that each item of the states could have unique ID's in the page.

eg could be, not sure how the parsing would work though.

/**
  * @name Input Number (Keyboard)
  *
  * @description An input that shows a pure numeric keyboard on mobile devices.
  *
  * @state :hover - Hover
  * @state :focus - Focus
  * @state :disabled - Disabled
  *
  * @markup
  * <label for="input-password-@state" class="label">Input Number</label>
  * <input id="input-password-@state" class="input input--number @state" type="text" pattern="\d*" />
  */

The markup parser (as prototype of any multi-line parser) does not correctly determine the end of the current multi-line comment segment.

This is the problematic code:

// find the next instance of a parser (if there is one based on the @ symbol)
// in order to isolate the current multi-line parser
var nextParserIndex = block.indexOf('* @', i+1),

I think the indexOf('* @') call assumes a situation where comments are written in the following style example:

/**
 * @markup
 * <button>click</button>
 *
 * @state :hover - When mouse rolls over
 */

If this style of commenting (with leading *'s each line) is not followed, the nextParserIndex will not be detected and the markup section is assumed to last the rest of the comment block. Adding parseable lines below a markup section like in the example above will result in those lines being included in the markup.

Would be really helpful to be able adding more text in description

/**
  * @name Button
  * @description: 
           Your standard form button.
           With extended description.
  * 
  * @markup
  *   <button class="button">This is a button element</button>
  */ 

Having this feature, It will be also possible to add Markdown support, which is essential for semi-complex documentation pages.

I submitted a pull request, but then abandoned it, because I wasn't able to make it. I submitted a separate issue with more detail.

P.S. Great talk today at jQueryTO. I am really excited to try DSS, as the CSS for a project I am involved with is starting to sprawl out of control. I think decent documentation, and a style guide, will really help get it back on track.

I understand this grunt-task is not ready to be used.
But I can't make work the bin too.

➜  styles git:(master) ✗ bin/dss
path.existsSync is now called `fs.existsSync`.

/Users/MoOx/Dropbox/Development/_clients/Jirafe/core/assets/styles/bin/dss:17
require(dir).Build(__dirname);
             ^
TypeError: Object function (){} has no method 'Build'
    at Object.<anonymous> (/Users/MoOx/Dropbox/Development/_clients/Jirafe/core/assets/styles/bin/dss:17:14)
    at Module._compile (module.js:449:26)
    at Object.Module._extensions..js (module.js:467:10)
    at Module.load (module.js:356:32)
    at Function.Module._load (module.js:312:12)
    at Module.runMain (module.js:492:10)
    at process.startup.processNextTick.process._tickCallback (node.js:244:9)

Is there a example somewhere ?

Hello,

While using DSS in our project we noticed that sometimes @markup is rendered on top of the code example and the rendered markup, this is being caused because this comparison:

  if (line && line != '@markup')

Is not strong enough for strings comparison.

The fix is to change it to:

 if (line && && line.indexOf('@markup') == -1)

For which a pull request is being made: #62

I have button styles that can be applied to both <a> and <button> elements, so I'd like to include both markup examples:

/**
  * @name Button
  * @description Your standard form button.
  * 
  * @state .is-primary - Indicates button is the primary action.
  * @state .is-smaller - A smaller button
  * 
  * @markup
  *   <button class="button">This is a button element</button>
  *
  * @markup
  *   <a href="#" class="button">This is an a element</button>
  */

However, this currently does not work. The line that is sent to the markup parser both times is still the first one. Here's the object I get from the above:

{
    "blocks": [
        {
            "name": "Button",
            "description": "Your standard form button.",
            "state": [
                {
                    "name": ".is-primary",
                    "escaped": "is-primary",
                    "description": "Indicates button is the primary action."
                },
                {
                    "name": ".is-smaller",
                    "escaped": "is-smaller",
                    "description": "A smaller button"
                }
            ],
            "markup": [
                {
                    "example": "   <button class=\"button\">This is a button</button>\n  ",
                    "escaped": "   &lt;button class=\"button\"&gt;This is a button&lt;/button&gt;\n  "
                },
                {
                    "example": "   <button class=\"button\">This is a button</button>\n  ",
                    "escaped": "   &lt;button class=\"button\"&gt;This is a button&lt;/button&gt;\n  "
                }
            ]
        }
    ]
}

I've tried fixing it myself, but I'm having a hard time figuring out why the parser function in the parse method can return the correct line for multiple @states but not for multiple @markups. If this isn't on your roadmap, then I'm hoping you can explain a little about how that works so I can write my own parser method.

Please and thank you.

EDIT: I should elaborate and mention that I understand I could do:

/**
  * @name Button
  * @description Your standard form button.
  * 
  * @state .is-primary - Indicates button is the primary action.
  * @state .is-smaller - A smaller button
  * 
  * @markup
  *   <button class="button">This is a button element</button>
  *   <a href="#" class="button">This is an a element</button>
  */

However, we're using the DSS as a separate library and not in conjunction with grunt-dss. We have a need to list those markup examples in separate chunks.

I'm not exactly sure why, but the fs.readdir callback never gets executed. It's as if the event loop is not seeing that there are any io functions waiting, and just exits.

Yep, somehow in the last week I broke everything but .css parsing. This means any comment blocks using // style of comment syntax aren't being parsed properly (only /* */ works). Hoping to fix this within the next few hours.

It seems that markup doesn't contains any whitespace, it's kind of problematic when you have something like a <table> to document (code is unreadable). Maybe we should not trim but instead just remove some spaces to get something indented ?

This is unnecessary and just looks gross to have the generated .html files mixed with the .mustache files after building.

There's a lot of redundant code now that we're using Grunt and require Wrench. My guess is that the library can be brought down to 250-300 lines if we use these tools effectively.

We need more robust and fool-proof parsing. Currently, the implementation is pretty benign (lots of regex matching, normalizing strings, half-hazard .replace() calls and an overall very rudimentary version of a syntax tree).

I was trying to write unit tests last week to address some issues/inconsistencies I saw with the latest updates I made (as #67 also notes) and I couldn't help but take note of other projects that provide better syntax trees and parsing. At this point I'm leaning towards gonzales-pe over a more barebones approach with peg.js.

Open to ideas/suggestions here.

Peg.js would allow us to define more robust parsing but it feels like I'd be duplicating a lot of the efforts of gonzales-pe to get enhancements, we eventually want, like mixin and variables support (#45).

Is it possible to get compile attribute selector states?

@state [disabled] -> ".attr-disabled"

If not, that would be awesome!

This seems like a really useful tool but the docs could use an update. With more complete examples starting from the beginning not from the end. I like DSS over the other generators because it allows you to use scss comments.

In your only example on how to use DSS you just have this

var lines = fs.readFileSync('styles.css'),
    options = {},
    callback = function(parsed){
      console.log(parsed);
    };
dss.parse(lines, options, callback);

I'm assuming fs is a node package, and when I looked into it here it says that this package has been unpublished. Also I have no idea the context of where to put this code at to get this to work.
I'm currently using gulp as my task runner because it's not as bloated as grunt. There is a gulp-dss package available but the documentation there is sub par. There are only 2 options, and neither of them are to add a custom parser.

For our project we are implementing a custom parser which parses multiline fields with markdown formatting.

Empty lines within markdown denote separation between paragraphs and are therefore important to retain.

I believe this is the part of the code that strips empty lines in the _dss.parse function:

// Remove extra whitespace
block = block.split('\n').filter(function(line) {
    return (_dss.trim(_dss.normalize(line)));
}).join('\n');

For other usecases like markup they could be stripped but for flexibility I think it should be left to the custom parsers instead of the initial 'prep' cycle in DSS.

To handle to base url of the templates assets, an option is required IMO.

It's just an idea, because for now I need to do something like that for some color

// @name Main colors
// @description Our brand colors
// @markup
//     <strong>Don't use this markup</strong>
//     <p class="color__blue">$color__blueblue</p>
//     <p class="color__orange">$color__orange</p>
//     <p class="color__green">$color__green</p>
//
$color__blue: #06b3a5;
$color__orange: #e4644b;
$color__green: #99CC33;

// styleguide only
.color__blue { background: $color__blue }
.color__orange { background: $color__orange }
.color__green { background: $color__green }

Would be cool to found a way to doc some variables. But for px values & other things we need to find a idea.

Noticed this bug after moving to Grunt.js, guessing I removed some code in a refactor that was wrapping comment blocks in their specific sections.

Right now the DSS clones the template directory verbatom. This means .mustache files are included in the output directory along with the .html files. Since they are sort of useless at that point, it would be better to remove them from the cloning process.

The unit tests added in #66 are failing.

Hello,
I'm trying to use DSS to parse a directory of Sass files that has nested directories and files within those directories. To do this I've written a task using glob and read-multiple-files which works perfectly as long as the files are in the main sass directory. I've uploaded a zip file to demonstrate this: http://dev.reintroducing.com/2015/dss.zip

If you unzip that and run node index.js from the command line in the directory you'll see that the generated dss.json file doesn't have the comment from the file in sass/common/_breadcrumbs.scss. Now move the breadcrumbs file into the same directory as _buttons.scss and run the command again and you will see that it's being generated properly.

Inside of index.js and in the glob portion if you log the files param you'll see in both cases the files are correct, in both cases the contents inside of readMultipleFiles are correct, yet the parsed file just has an empty "blocks" array unless the files are on the same level. Obviously this is not desired as seldom do Sass files live in the same directory at all times.

Could you please take a few minutes and look at the files to see what I'm doing wrong? Is this not a good way to utilize DSS? If not, what is the best way to run DSS to parse a directory of Sass files which are nested in other directories? The example in the readme doesn't demonstrate this rather an example of running it on a single file.

Thank you very much for your hard work on this wonderful tool. Please let me know if there is anything else you need from me to try and help troubleshoot this.

I'm evaluating style guide generators, DSS didn't really come up in my research, but someone mentioned it, and I notice there's no online demo linked.

Is it fair to say that DSS is a styleguide generator, and is there maybe a project somewhere that would serve as a decent example?

To check that the task work correctly, we could add Travis-CI to run the default task, to check it works nicely.
Also works for PR, tell you if it broke stuff :)
I setup Travis on multiple project I can help if you're interested, but first, you need to go on travis-ci website, login with github & activate travis-ci for this repo. I can do the rest.

Could you please add custom fields support in parser?

/**
  * @name Button
  * @description Your standard form button.
  * 
  * @custom Some custom info
  * @templateName Link to template
  * 
  * @markup
  *   <button class="button">This is a button element</button>
  */

This fields will allow to integrate some custom features on top, like template include support. We would really love this feature for our SourceJS integration.

Add some hawt tests! /cc @jeffjewiss Please give a status update on this when you get a chance.

I already did this to the file but I thought other people might like to see this feature added. In the _dss.parse function I added the following.

After the index = block.indexOf(line); variable, inside the parser function I added this.

var endOfBlockRegex = /\n\s*#{{(\d*)}}/,
    endOfBlock = block.match(endOfBlockRegex)[1],
    block = block.replace(endOfBlockRegex, "");

Then added endOfBlock to line 205

line[name] = (variable) ? variable.apply(null, [index, description, block, file, endOfBlock]) : '';

Then on line 314 inside if statement that stores the current block if done. I added .concat("\n #{{" + lineNum + "}}") to the current_block

_blocks.push(_dss.normalize(current_block.concat("\n #{{" + lineNum + "}}")));

The reason why I added this is so that I can easily get the css directly after the block so I don't have to duplicate scss that is already after the current block. Things like variables, functions, mixins, and placeholders.

It looks like the markup parser isn't working properly since the switch to grunt. Need to check how the lines/comment block are being passed to dss.parser().

There seems to be an issue when the default location is used, the task isn't run async, or the task is never completed.

I keep getting build errors sent to my email when there doesn't seem to be an issue. I've also noticed (in the last 48 hours) that the image/statues fluctuates from build:error and build:passing. That said, my last PR was passing before I merged. What's going on? Are the tests being run all the time and somehow fail every once in awhile?

Is it possible to get the source associated/that follows a comment block e.g.

If I wanted to have my colour variables in a sass file:

//
// @name Variables
// @description Variables in my style guide
// 
// 

$colour1: #FFF;
$colour2: #EEE;
$colour3: #666;

If I wanted to get as json representation of my the actual hex values (to output in my style guide) how would I go about this?

The way the current structure works there is an issue consuming or using dss outside of the Grunt task itself. This makes the library, as a whole, less reusable. The original version was just in node and could be run by itself, since changing over to Grunt, we've not created a hard dependancy on it which makes it less appealing for any other dev that may want to use the parser in a different way.

Let's look at making the structure of the parser aspect of the library more modular so that we can have a number of different use cases outside of the Grunt build task (which deals specifically with generating documentation with the mustache templates defined).

I'm trying to use prism and I need the ability to pass a language param to the code

<div>
 <h3>Example</h3>
 <div class="example">
  {{ markup.example | safe }}
 </div>
 <h1>{{ state.name }}</h1>
 <pre><code class="language-{{ markup.lang }}">
{{ markup.escaped }}
 </code></pre>
</div>

I figured it could work something like this to make it simple.

@markup scss
...

I like the syntax of DSS very much, especially when compared to KSS ( http://warpspire.com/kss/) because its more strict. But KSS has the advantage that it allows to express a hierarchical relationship between modules (through Styleguide X.X.... annotation). This makes it possible to group modules into logical chunks.

It would be nice to have some kind of syntactic sugar to express hierarchical relationships in DSS, too.

What I don't like in KSS is that the explicit numbering of the annotations is given by the author through Styleguide 1.5.. This leads to regular refactoring in bigger projects.

One possible solution would be to just allow the annotation of the group depth in which the module should sit, e.g.

//
// @name Buttons
// @description There are multiple button types.
// @depth 1
// 

... CSS code

//
// @name Regular Button
// @description Your standard form button.
// @depth 2
// 
// @state :hover - Highlights when hovering.
// @state :disabled - Dims the button when disabled.
// 
// @markup
//   <button>This is a button</button>
// 

... CSS code

//
// @name Special Button
// @description A special button.
// @depth 2
// 
// @state :hover - Highlights when hovering.
// @state :disabled - Dims the button when disabled.
// 
// @markup
//   <button>This is a button <strong>with a fancy label</strong></button>
// 

... CSS code

The above code should then generate a hierarchical JSON output similar to:

{
  "name": "Buttons",
  "description": "There are multiple button types.",
  children: [{
    "name": "Regular Button",
    "description": "Your standard form button.",
    ...
  }, {
    "name": "Special Button",
    "description": "A special button",
    ...
  }]
}

I noticed uncommon practice you're following, defining two types of state contents. If there's only one state, DSS returns an object, and in case with 2 and more states it returns an array.

This is very confusing and make rendering templates more complex, I think almost every developer will expect to have only an array.

Current output:

{
        "name": "Default",
        "state": [
            {
                "name": ".button-pro_big",
                "escaped": "button-pro_big",
                "description": "Bigger version"
            },
            {
                "name": ".button-pro_big2",
                "escaped": "button-pro_big2",
                "description": "Highlights when hovering."
            }
        ],
        "markup": {
            "example": "<button class=\"button-pro\">Click me</button>",
            "escaped": "&lt;button class=\"button-pro\"&gt;Click me&lt;/button&gt;"
        }
    },
    {
        "name": "Disabled",
        "state": {
            "name": ".button-pro_big",
            "escaped": "button-pro_big",
            "description": "Bigger disabled version"
        },
        "markup": {
            "example": "<button class=\"button-pro button-pro_disabled\">Click me</button>",
            "escaped": "&lt;button class=\"button-pro button-pro_disabled\"&gt;Click me&lt;/button&gt;"
        }
    }
}

Expected output:

{
        "name": "Default",
        "state": [
            {
                "name": ".button-pro_big",
                "escaped": "button-pro_big",
                "description": "Bigger version"
            },
            {
                "name": ".button-pro_big2",
                "escaped": "button-pro_big2",
                "description": "Highlights when hovering."
            }
        ],
        "markup": {
            "example": "<button class=\"button-pro\">Click me</button>",
            "escaped": "&lt;button class=\"button-pro\"&gt;Click me&lt;/button&gt;"
        }
    },
    {
        "name": "Disabled",
        "state": [
            {
                "name": ".button-pro_big",
                "escaped": "button-pro_big",
                "description": "Bigger disabled version"
            }
        ],
        "markup": {
            "example": "<button class=\"button-pro button-pro_disabled\">Click me</button>",
            "escaped": "&lt;button class=\"button-pro button-pro_disabled\"&gt;Click me&lt;/button&gt;"
        }
    }
}

It looks like the npm package has not been published for 2 years (currently 1.0.4). There are quite a few issues that you have closed that I could not use with the latest npm package (1.0.4). I have installed via github url, but it would be nice for these changes to be published. Thank you.