So much info

[netgfx]

Hello I have been strugling with documentcss for the past 6 hours and I barely managed to create a sample of the buttons style.

So I'm wondering, is there a .zip I can download (pre-compiled) that I can tinker and get the end-result?

Or is there some default folder structure that I can follow and it will guarantee create a result? (no the documentation folder structure is lacking serious consistency or info)

Also (because it is highly unclear) does documentcss support scss files as stylesheets?

And finally how can I create a custom .scss, .less, .css or whatever style to "change" the default styles in a way that it will get compiled inside static.css?

thanks...

[tomgreever]

Hey Michael, I feel your pain. We are working up some specs to make this much easier.

In the meantime, trying forking from this repo: https://github.com/bitovi/bootdocs run npm install and then grunt to generate the docs. This project is nothing more than a series of less and md files with the Bootstrap documentation in it. It also has several different "themes" you can use, modify, etc... I'm hoping this will at least get you up and running with a default structure and config, then you can start customizing it for your project.

Let me know how it goes. -Tom

[netgfx]

Thanks I will try it out.

[lkodai]

Hey Michael,

DocumentCSS will document scss files. You just have to tell it to look for them in your config file. Here's Bootdoc's documentjs.config file:

{
  "siteDefaults": {
      "templates": "themes/default/templates",
      "static": "themes/default/static"
    },
  "sites": {
    "styles": {
        "glob": "{less,docs}/**/*.{css,less,md}",
        "dest": "styleguide",
        "parent": "styles"
    }
  }
}

On line 8 where it says "glob" you can change it to say:

"glob": "{scss,docs}/**/*.{css,scss,md}",

And that will tell the system to look for your scss and output *.scss.html files instead of *.less.html files in your destination directory (in the example above it's in the styleguide folder).

Hope that helps a bit too.

[netgfx]

That is for bootdoc, is there something similar for documentcss? (about scss files) Because the above doesn't output any .scss.html files do I need any other dependency apart from the ones installed with "npm install -g documentjs" ?

[tomgreever]

@netgfx I'm not sure what you mean. Bootdocs is just a sample DocumentJS/CSS project. If you run npm install on Bootdocs it should install all the dependencies you need.

DocumentCSS will document any type of file. It simply looks for the comments that it recognizes. You tell DocumentCSS what file type to search for by using something like "glob": "{scss,docs}/**/*.{css,scss,md}" in your documentjs.json file which tells it to only look in the scss and docs folder, and to only look at files with .css, .scss, and .md extensions.

It's not a matter of DocumentCSS 'supporting' .scss - you just have to tell it what files to search. In theory, you could have it search all .xml or .txt files if you add those extensions to the glob pattern.

[lkodai]

@netgfx This is an honest question, if you're not seeing any errors or any .scss.html files, have you used any tags in your actual scss files for documentcss to find? Something like the code below within your typography scss file:

/**
  * @stylesheet typography.scss Typography
  * @parent styles
  *
  * @description
  * Typography helps set the tone of the website. The specific details of the type system are demonstrated below.
  *
  **/

That should produce a typography.scss.html page when you run documentcss. The @stylesheet tag titles the page, the @parent tag tells it where in the navigation to put the page, while @description is of course, any text explanation of what's in the code.

[netgfx]

Basically what I'm struggling with is that I have this:

/**
  * @stylesheet buttons.scss Buttons
  * @parent styles
  *
  * @description
  * All defined button styles and states belong here, including any "helper class" button style options, like `default`, `primary` etc.*
  * The same button styles have been applied to a button class, for use on other html elements emulating a button.
  *
  * 
  * @demo demos/buttons.html
  * 
  *
  **/

in a .scss file but the .scss.html is not produced, if I make this in a .less file the .less.html gets rendered normaly. And yes no errors.

[ramblinjan]

@netgfx What does your documentjs.json look like?

[brandonreid]

+1 for a pre-built example to follow. Maybe even like a starter boilerplate. Better documentation of the document.json options would be super helpful too. Been struggling hard but I do believe this will help me finally make a pattern library that can be maintained! If I wrap my head around this thing I'll def publish a boilerplate if no one else does.

[brandonreid]

Man... After so much wrestling I'm feeling so defeated.

The only way I could get a demo to work, after following the documentation step-by-step multiple times is to manually drag the demos folder into the generated styleguide folder, but it had none of the styles I set in the very stylesheet declaring the header and description in the view..

Couldn't get the bootdocs repo going either, all sorts of grunt errors claiming things like @media and @opacity aren't recognizable tags and stuff.

I'll have to manually maintain a jekyll site and lose out on all the awesome potential with this idea. I really hope you guys take it further, it could really rock the pattern library movement. Perhaps something totally separate from documentjs. I'll totally volunteer to make a hipster landing page for it if you guys do!

[tomgreever]

@brandonreid thanks for chiming in and sharing your experience. We think it's a really valuable tool and has great potential, but agree that the setup is difficult and frustrating. We use it every day in our client projects, so it is possible to make it work. Once you get past the set up, it's really rewarding to use.

If you guys don't mind, maybe I can screen share with you some time and see what it's doing for you. Would you be willing to do that? @netgfx ? I'd love to see if we can get it running for you.

As an aside, DocumentCSS does not do anything at all to the demos. The @demo is just a link/reference to the demo file, so you do have to manually move the demos where you want them. We usually overcome this by creating a grunt task that copies the demos. I would love that to be a feature.

[brandonreid]

@tomgreever I'd love to have a hangout sesh anytime and see if you might be able to help me out. Once I've got it running, I'll definitely make a ready-to-go boilerplate repo with said grunt/gulp task and what not.

[tomgreever]

@brandonreid email me tom@bitovi.com and we'll set something up.

Bootdocs was meant to be that boilerplate, but maybe it has too much going on and we need something much simpler with just a couple of pages.

[gabrielpugliese-luizalabs]

Hi,

I'm struggling with documentcss too. I tried to even create a simple css but had no success. Here is a clonable repo, what am I doing wrong there? https://github.com/gabrielhpugliese/documentcss-test

I've also tried to clone https://github.com/bitovi/bootdocs but the grunt task do not work raising the error:

[ml-site]gabrielpugliese@sapobook ~/Test/bootdocs(master) $node_modules/grunt-cli/bin/grunt documentjs
Running "documentjs-orig" task
Generating styles at styleguide
WARNING!!
There is no @media tag. did you mean @add ?

WARNING!!
There is no @media tag. did you mean @add ?

WARNING!!
There is no @media tag. did you mean @add ?

WARNING!!
There is no @media tag. did you mean @add ?

WARNING!!
There is no @media tag. did you mean @add ?

WARNING!!
There is no @media tag. did you mean @add ?

WARNING!!
There is no @media tag. did you mean @add ?

WARNING!!
There is no @opacity tag. did you mean @option ?

{ [Error: ENOENT, lstat '/Users/gabrielpugliese/Test/bootdocs/node_modules/documentjs/documentjs/node_modules/steal/steal.production.js']
  errno: 34,
  code: 'ENOENT',
  path: '/Users/gabrielpugliese/Test/bootdocs/node_modules/documentjs/documentjs/node_modules/steal/steal.production.js' }
Warning: ENOENT, lstat '/Users/gabrielpugliese/Test/bootdocs/node_modules/documentjs/documentjs/node_modules/steal/steal.production.js' Use --force to continue.

Aborted due to warnings.

[tomgreever]

@gabrielpugliese-luizalabs you can try https://github.com/brandonreid/documentcss_starter-kit from @brandonreid

I will look at that error you're getting and see if I can help.

[justinbmeyer]

@gabrielpugliese-luizalabs what version are you using? Make sure to npm install documentjs@0.3.6

[gabrielpugliese-luizalabs]

@justinbmeyer "documentjs": "^0.4.1" in package.json

@tomgreever Thx, gonna try it!

[gabrielpugliese-luizalabs]

Well, tried the start-kit with node5 and npm3 but:

[new-node]gabrielpugliese@sapobook ~/Test/documentcss_starter-kit(master) $node_modules/gulp/bin/gulp.js dev
/Users/gabrielpugliese/Test/documentcss_starter-kit/node_modules/accord/lib/index.js:31
      throw new Error(name + " version " + version + " is not currently supported");
      ^

Error: less version 1.7.5 is not currently supported
    at Object.exports.load (/Users/gabrielpugliese/Test/documentcss_starter-kit/node_modules/accord/lib/index.js:31:13)
    at Object.<anonymous> (/Users/gabrielpugliese/Test/documentcss_starter-kit/node_modules/gulp-less/index.js:9:29)
    at Module._compile (module.js:425:26)
    at Object.Module._extensions..js (module.js:432:10)
    at Module.load (module.js:356:32)
    at Function.Module._load (module.js:313:12)
    at Module.require (module.js:366:17)
    at require (module.js:385:17)
    at Object.<anonymous> (/Users/gabrielpugliese/Test/documentcss_starter-kit/gulpfile.js:3:12)
    at Module._compile (module.js:425:26)

[brandonreid]

@gabrielpugliese-luizalabs Try to remove gulp-less from package.json, then run npm install gulp-less, get a version of less that works for ya.

[gabrielpugliese-luizalabs]

Thx @brandonreid, but didn't work. Tried to update everything without success too :( I'm taking a break right now, spent too much time with that.

[joeHillman]

I've been struggling with this for a little while now. The biggest problem I had was getting the index page to render correctly. It would default initially to a placeholder page. I was able to get the @stylesheet, @styles, @demos working and the @group working in some regards, but am thinking this will fall into place now with the @page straightened out.

Looking at the generated styleguide had helped me out a bit while navigating the setup.

After looking closer at the configuration, it wound up being a dumb mistake anyways that fixed up my pages. The expression was incorrect as it had spaces after the commas.

A good reminder to get from the keyboard from time to time!

{
  'sites': {
    'styles': {
      'parent': 'styleguide',
      'glob': 'styles/*.{md,scss}',
      'dest': 'styleguide'
    }
  }
}

[brandonreid]

@gabrielpugliese-luizalabs FYI, I found the problem you probably encountered. Pushed updates to the starter kit if you want to give it another shot.

[gabrielpugliese-luizalabs]

Thanks @brandonreid !