sassdoc / sassdoc Goto Github PK

I would like to be able to use Sass to generate the stylesheet for the documentation. Would it be easy @FWeinb?

Hi @hugogiraudel

Consider the following example:

/**
 * Description of my variable
 * ---
 * @datatype string
 */
$some-other-variable: "a" !default;

/**
 * Defines whether the lib should support legacy browsers (e.g. `IE 8`).
 * ---
 * @since 0.3.9
 * @todo Nothing. It's awesome.
 * @link https://github.com/HugoGiraudel/SassDoc SassDoc
 * @datatype Bool
 */
$legacy-support: true !global;

The first variable documentation does not render at all. The second variable is missing the description. Any ideas why the first variable is not included in the rendered doc?

It would be interesting to have the possibility to exclude a whole block from docs, if needed.
While still being able to comment it in code with the same logic.

For instance a variable used internally for storage or manipulation.
But that could as well happens with some internal functions/mixins I guess.

Could be called @usedin according to #15.

From @valeriangalliat in #15:

@usedin is interesting, but I'm not sure about the naming. @see would be more standard, but the semantic is not exactly the same.

From me in #15:

I like the idea but not the name. Perhaps @see would be enough for me. That being said, I want to have something like that so I'm okay.

From @valeriangalliat in #15:

@usedin is interesting, but I'm not sure about the naming. @see would be more standard, but the semantic is not exactly the same.

From @alademann in #11:

The only difference would be that the expected value of @see is a fully-qualified URL, and my vision of @usedin would have an expected value of a named string(s) which would leave room for the ability to cross-link modules, functions, etc... in the documentation. This would be similar to @requires - but in the reverse direction - x uses y instead of y requires x.

In the future, the generated docs could list named strings that were referenced in a @usedin declaration and show/link to all the vars, mixins and functions that are used there.

Let me know if that makes sense - or if you think we could just extend @see so that it accepts fully qualified urls or strings that would be "indexed" as named entities.

From me in #11:

Based on this asumption, we could use the same process we used for aliases. At first, I implemented @alias and @Aliased. The first says that the documented function/mixin is an alias of the function named after the alias. Meanwhile, the @Aliased dirctive was supposed to go on the main function, linking back to the alias (think of it as "aliased by").

Valérian declined the implementation, and he was definitely right to do so. In the end, we have @alias which defines if the documented function/mixin is an alias of another function/mixin. Then we post process the data to define an aliased key, which contains the name of all aliases for each function.

I suppose we could do exactly the same for used. Post-process the data, and based on the @requires directive, fill the used key for each item.

Following of #34

Variable formatted on a multi-line fashion are ignored.
Even with adding the !global flag.
Seems really tight to line breaking the map because I tested with:

$map: (

) !global;

and it still doesn't show up.

Refers to SassyIcons doc

Would be cool to be able to search and filter documented items.

Already added to real-parser.

I want to add a footer to generated docs. Not only will it contain a small "Built with SassDoc" link on the right, but also informations about the documented project on the left, given from view.json.

@pascalduez and I thought about:

// view.json
"project": {
  "name": "My Awesome Project",
  "url": "http://my-awesome-project.com",
  "license": "MIT",
  "version": "1.3.37"
}

<footer class="sassdoc__footer">
  <div class="container">
    {% if project %}
      <div class="sassdoc__footer-project">
        <!-- Name and URL -->
        {% if project.url %}
          <a href="{{ project.url }}">{{ project.name }}</a>
        {% else %}
          <span>{{ project.name }}</span>
        {% endif %}

        <!-- Version -->
        {% if project.version %} - {{ project.version }}{% endif %}

        <!-- License -->
        {% if project.license %}, under {{ project.license }}{% endif %}
      </div>
    {% endif %}

    <span class="sassdoc__footer-watermark">Built with <a href="https://github.com/HugoGiraudel/SassDoc">SassDoc</a>.</span>
  </div>
</footer>

In case you wonder, both version and title keys from view.json would be moved to project object.

Is everybody okay with this? @valeriangalliat, @FWeinb?

I think it would be practical to have a --version CLI option to check which sassdoc version is installed:

$ sassdoc --version
--version is not recognized

When i try to launch sassdoc i receive this error message:

env: node\r: No such file or directory

Regular expressions are not powerful enough.

We need to write a real parser.

Great project! This project (and many more of your projects) definitely needs to be listed here so that people can find them: http://www.sache.in/

A nice improvement would be to add group creation and ordering.
Right now the codebase is split in functions, mixins, variables. In that order.

With groups, one could create an helpers, API, output, whatever group.
Group order or weights, would allow to organize groups by importance. Moving the public API on top, or the like.

From @gisu in #16.

I can start it but a few errors.

Added a File test.scss

// ---------------------------------------------------------
// @module core/modules/panels
// ---
// Flexible containers that help to isolate/provide context
// to other core elements in the platform.
// ---
// @since 0.2.1
// ---
// @example
//   <div class="panel panel-default">
//     <div class="panel-heading">
//       <h3 class="panel-title">Panel title</h3>
//     </div>
//     <div class="panel-body">
//       Panel content
//     </div>
//     <div class="panel-footer">
//       Panel content
//     </div>
//   </div>
// ---
// @link http://mystyleguide.com/core/modules/panels
// ---------------------------------------------------------


// @private @var $panel {map} - stores configuration options for .panel module
// ---
// @since 0.5.0
// ---
// @depends core/config/defaults, core/config/colors
$panel: (
  'base': (
    'default': (
      'text': $gray-dark,
      'bg': #fff,
      'bd': #ddd
    ),
    'success': (
      'text': $state-success-text,
      'bg': $state-success-bg,
      'bd': $state-success-bd
    )
  ),
  'body': (
    'padding': 15px
  ),
  'heading': (
    'padding': 10px 15px
  ),
  'footer': (
    'padding': 10px 15px
  )
) !default;


// @base panel
// ---
// Must be combined with one of the variant modifiers to gain styling.
.panel {
  foo: bar;
}

Started the process

$ sassdoc src/test doc --verbose
2014-06-25 14:34:24 Folder `doc` successfully removed.
2014-06-25 14:34:24 Folder `doc` successfully generated.
2014-06-25 14:34:24 Folder `src/test` successfully parsed.
2014-06-25 14:34:24 Documentation for folder `src/test` successfully generated.
{ [Error: ENOENT, mkdir '/usr/local/lib/node_modules/sassdoc/src/../doc/css']
  errno: 34,
  code: 'ENOENT',
  path: '/usr/local/lib/node_modules/sassdoc/src/../doc/css' }

The Index in /doc is have only a HTML Structure but no entrys. Didn't find the Stylesheet for the Doc.

Current:

/**
 * @example
 * first(a b c)
 * // a
 */

I would like to have:

/**
 * @example scss
 * first(a b c)
 * // a
 */

So that we can set different syntax for Prism.js in the generated docs, with scss as a fallback.

From @alademann in #15:

Modular (BEM/OOCSS) Hierarchy

• @module - define a file as a module.
  • @base - define a class/id as a "base" class/id for a module.
    • @element - define a class/id as a "element" class/id for a "base" class/id
    • @modifier {type} - define a class/id as a "modifier" class/id for a "base" or "element" class/id
      • The {type} would be "open-ended", but would be something like variant or state, for example.
• @depends - similar to @requires - except this would create a link to an external @module (or even some JS) that is not implied via the declared @base / @element / @modifier syntax.
  • allow multiple via comma-separated list - or multiple @depends lines (see $panel var example below)?
• @extends - similar to @depends, but this type of element would automatically extend a dependency instead of implying that the other module/component had to be used/included separately.

From @valeriangalliat in #15:

I like the idea of documenting BEM classes.

Like the name and value for variables, we can also get the class name by looking the line after the docblock, it's redundant to add it after the annotation. But maybe it can be tricky to find it in the selector for more complex cases?

From me in #15:

Okay, I like that. Although I don't think it's possible to do that with regular expressions right now so until we have a dedicated parser, this probably won't work.

I have hard time seeing the difference between @Depends and @requires. As far as possible, I'd like to keep only one, unless both are serving strictly different purposes.

We have a real issues with broken links here. The problem happens anywhere we cross-link items.

For instance if A requires B, but B is private and private are not displayed, link from A to B is broken because B doesn't exist. Same for usedBy.

One possible solution would be to move access to context, so that whenever we cross-link items, we can know the access level of the linked item.

@hugogiraudel there is no hurry to handle this ;-)
I'm just listing here some thingies I noticed or are unclear to me.

Refers to SassyIcons doc

• Documented items count in header is not properly updated
• Functions category title and item in map is displayed even if no items
• If you have some parenthesis in a parameter description it breaks a bit the whole doc block
• requires aka usedby is printed as requires whereas it should be required by or something.
• Variables without !global are still output. But not in map...
• Variable formatted on a multi-line fashion are ignored, even with !global
• ...

Hugo...

I'm curious if it would be possible to support non-mixin/function documentation? I'm needing something like http://sassdocjs.com/doc/, but that repo's code is borderline un-maintainable IMO.

The function and mixin parsing is awesome - and I need that piece. But in order to document a modular front-end framework built with Sass, there are a few more pieces to the puzzle for me. (These are all just suggestions / open for discussion obviously)

First thing is... I need a way to document some basic Sass $variables (and maybe event some nifty Sass map-typed variable traversal).

I also need to document / describe relationships / dependencies between Sass entities (classes, placeholders, ids, etc...) and entire modules (read: Sass partials) in a very large, very modular BEM/OOCSS platform.

I would propose adding the following definitions (I also understand if this needs to be broken into separate issues, but wanted to get a discussion rolling in one place):

Variables

• @var {type | other type} $name (default value) - description of var
  • I'm assuming combining this with something like @private means that it is scoped to a module, and combined with @public means that it would be declared using !global?
  • Vars would need to be able to declare dependencies on other vars / modules containing vars (see example $panel var below)

Meta

• @example - provide brief HTML implementation example
• @usedin - similar to @link - provide an example where a developer could see it being used
• @since - provide a version when a specific class/function/mixin was made available
• @support - list of supported browsers for a module

Modular (BEM/OOCSS) Hierarchy

• @module - define a file as a module.
  • @base - define a class/id as a "base" class/id for a module.
    • @element - define a class/id as a "element" class/id for a "base" class/id
    • @modifier {type} - define a class/id as a "modifier" class/id for a "base" or "element" class/id
      • The {type} would be "open-ended", but would be something like variant or state, for example.
• @depends - similar to @requires - except this would create a link to an external @module (or even some JS) that is not implied via the declared @base/@element/@modifier syntax.
  • allow multiple via comma-separated list - or multiple @depends lines (see $panel var example below)?
• @extends - similar to @depends, but this type of element would automatically extend a dependency instead of implying that the other module/component had to be used/included separately.

Example

Below is an example "module" - in a platform that shows a little bit of what I'm envisioning / describing above.

• This file would be located in a taxonomy such as sass/core/modules/_panels.scss.

// ---------------------------------------------------------
// @module core/modules/panels
// --- 
// Flexible containers that help to isolate/provide context 
// to other core elements in the platform.
// ---
// @since 0.2.1
// ---
// @example
//   <div class="panel panel-default">
//     <div class="panel-heading">
//       <h3 class="panel-title">Panel title</h3>
//     </div>
//     <div class="panel-body">
//       Panel content
//     </div>
//     <div class="panel-footer">
//       Panel content
//     </div>
//   </div>
// ---
// @link http://mystyleguide.com/core/modules/panels
// ---------------------------------------------------------


// @private @var $panel {map} - stores configuration options for .panel module
// ---
// @since 0.5.0
// ---
// @depends core/config/defaults, core/config/colors
$panel: (
  'base': (
    'default': (
      'text': $gray-dark,
      'bg': #fff,
      'bd': #ddd 
    ),
    'success': (
      'text': $state-success-text,
      'bg': $state-success-bg,
      'bd': $state-success-bd
    )
  ),
  'body': (
    'padding': 15px
  ),
  'heading': (
    'padding': 10px 15px
  ),
  'footer': (
    'padding': 10px 15px
  )
) !default;


// @base panel
// ---
// Must be combined with one of the variant modifiers to gain styling.
.panel {
  foo: bar;
}

// @element panel-body
// ---
// Panel contents
.panel-body {
  foo: bar;
}

// @element panel-heading
// ---
// Optional heading above panel contents
// --
// @link http://mystyleguide.com/core/modules/panels-with-heading
.panel-heading {
  foo: bar;
}

// @element panel-title
// ---
// Within panel-heading, strip any `h*` tag of its default margins for spacing.
.panel-title {
  foo: bar;
}

// @element panel-footer
// ---
// Optional footer below panel contents
.panel-footer {
  foo: bar;
}

// @element panel>list-group
// ---
// List groups in panels
// ---
// @depends core/modules/list-groups
// ---
// @link http://mystyleguide.com/core/modules/panels-list-group
// ---
// @example
//   <div class="panel panel-default">
//     <!-- Default panel contents -->
//     <div class="panel-heading">Panel heading</div>
//     <div class="panel-body">...</div>
//   
//     <!-- List group -->
//     <ul class="list-group">
//       ...
//     </ul>
//   </div>
.panel > .list-group {
  foo: bar;
}

// @element panel>table
// ---
// Tables in panels
// ---
// @depends core/modules/tables
// ---
// @link http://mystyleguide.com/core/modules/panels-tables
// ---
// @example
//   <div class="panel panel-default">
//     <!-- Default panel contents -->
//     <div class="panel-heading">Panel heading</div>
//     <div class="panel-body">...</div>
//   
//     <!-- Table -->
//     <table class="table">
//       ...
//     </table>
//   </div>
.panel > .table {
  foo: bar;
}

// @modifier {variant} default
.panel-default {
    foo: bar;
}

// @modifier {variant} success
.panel-success {
  foo: bar;
}

// @modifier {size-variant} small
.panel-sm {
  foo: bar;
}

// @modifier {state} is-focused
// ---
// @depends js/modules/panels
.panel.is-focused {
    foo: bar;
}

Thanks so much for discussing/considering this - I'm happy to do whatever I can to contribute if you think these are valuable additions to the repo. Any other thoughts on how to make this more intuitive are most welcome and appreciated!

Or Gulp. Whatever.

Now that we have quite a few things going on (Sass watching, JSHint...), perhaps having a more powerful than Make, task-based workflow wouldn't be such a bad idea, right?

@valeriangalliat, @FWeinb, what do you say?

Got an error when generating docs.

2014-07-02 23:24:51 Folder dok successfully removed.
2014-07-02 23:24:51 Folder dok successfully generated.
[TypeError: Cannot read property '1' of null]

I've run some test and I think this is a problem with my folder structure. It's like that:
assets -> scss -> mobile -> mobile.scss and folders with partials
When running sassdoc assets/scss dok --verbose for this structure I've got mentioned error.

But when I changes structure to:
assets -> scss -> global (folder with partials)
generating of documentation was successful.

Rather than copying the CSS file manually, we could copy the asset folder as whole. In case we are using several CSS/JS files, that would be easier.

Either we build the function ourselves, or we can use a package like ncp or wrench: http://stackoverflow.com/questions/13786160/copy-folder-recursively-in-node-js.

Any thought?

Might be useful to have a syntax to document maps, a per key/val documenting.
For instance configuration maps.

While we do cross-linking, there is no way to easily get the anchor of an item right now.

Possibly not forcing Swig. In any case, making the view more configurable.

I would like to make it possible for users to pass some values to the view, so the generated documentation looks a little more customized, starting with the title.

@valeriangalliat and I have talked about it and the simplest way to do that would be to join a .json or .yml file containing all the options. Then in the view, provide default if the required keys do not exist.

sassdoc path/to/source path/to/destination --config path/to/config.json
sassdoc path/to/source path/to/destination --config path/to/config.yml

It would probably look like this:

{
  "title": "Title here"
}

Or in YML:

title: "Title here"

Should we log when:

• an alias is not matching any item?
• a require is not matching any item?
• a type is not a valid Sass type?
• a link is not a valid URL?

Must a variable !global? Without !global no var would be indexed from the parser.

/**
 * Defines the Directory to the fonts
 * ---
 * @since 0.3.9
 * @datatype String
 */
$font-url: '../fonts/';

/**
 * Defines the Directory to the UI Images
 * ---
 * @since 0.3.9
 * @datatype String
 */
$img-url: '../img/' !global;

As of today, @deprecated message (if any) is being displayed when hovering [DEPRECATED], as a title attribute.

I understand this is far from ideal since most people won't hover the flag, thus won't ever see the message.

We need to find a way to display the @deprecated message more clearly. I suppose we could have something like any other tag, a title then the message underneath but I feel like there is already a lot of stuff going on under the code bloc.

Any idea welcome.

A bit nit-picking here, but could be interesting to have a visual or text information on required arguments (without a default value).
It's already stated whether the argument has a default value or not (at least in comments...).
But that could make it more straightforward I guess.

I have the case on SassyIcons where the type returned by some functions is spritemap.

type-of() returns compass::sassextensions::sprites::spritemap.
See http://pascalduez.github.io/SassyIcons/docs/#function-_sprite-map-get

So not sure what to document here. I guess I could go with String or * and a comment alongside. But does not sounds really accurate.

When using @requires with mixins, the anchor link points to #function-name instead of #mixin-name:

@mixin base {
    @content;
}

// Requires base
// ---
// @requires base

@mixin requires-base {
    @content;
}