Cut big problems into more simple ones

[valeriangalliat]

There's a lot of feature requests for SassDoc, that adds complexity to the core, for example to generate indexes for specific use cases in the template, parse stuff as Markdown, remove or mark items as disabled under certain conditions, etc.

I believe the core should remain as simple as possible, and these features should be externalized in their own Node.js modules, and used by any compliant theme.

For example, there could be a sassdoc-markdown module, that a theme could call to preprocess the ctx to parse things as Markdown; a sassdoc-group module to group and index the raw data under certain keys for the template to easily display grouped data, sassdoc-access to show or not private items, and so on.

Since all these functionalities are theme-dependant, they would be moved in the theme logic, but without adding a lot of complexity to the theme because they would live in their own Node.js modules (allowing any theme to reuse part of these functionalities).

[KittyGiraudel]

Fully okay with that. Let's hear @pascalduez and @FWeinb.

[FWeinb]

Can't :+1: this enough!

[KittyGiraudel]

@valeriangalliat, you're in charge?

[pascalduez]

I have mixed feelings about this, but at the end, if you guys think it is best, then I'm fully with you :-)

I already wrote that the api should be decoupled, especially the file/disk operations from data ones. The getData function is turning into a beast. So basically I really like the idea !

Just I have the impression that sometimes a module might be a bit too much for some of those tasks ? I'm curious to see the result actually.

[KittyGiraudel]

Summing up the current discussion with @FWeinb on http://tlk.io/sassdoc. Be sure to read it if you want extra informations.

SassDoc is doing too much right now. Its goal should be no more than:

1. Parse files.
2. Parse comments.
3. Generate an array of items.
4. Resolve cross-references (@requires, @see, ...)

That's it. To improve 4. we are thinking of improving the annotation plugin to allow the annotations to get called after the flat array is built. Currently, we resolve cross-references in the getData method, in a completely decoupled way from the actual annotation. What about something like this:

module.exports = {
  parse : function () {
    // This method is called to parse the annotation
  },

  resolve : function (flatArray) {
    // This method is called after all annotations are  parsed
    // Modify the flatArray (resolve link etc.)
    return flatArray;
  }
}

Anyway, this would leads us to a 3 layers system:

1. Grab the data (SassDoc)
2. Transform the data (new)
3. Display the data (theme)

This new second thing could be some kind of module that would turn the array of items returned by SassDoc into indexes for the view to use. Perhaps sassdoc-indexer or something.

Along the same lines, we could have some kind of sassdoc-transformer that would convert some fields, for instance the group names, as well as a sassdoc-markdown-transformer that would deal with this whole markdown thing.

[FWeinb]

We should also add the ability to define a default value in the plugin system.

[valeriangalliat]

@pascalduez I understand you want to abstract SassDoc's flow with streams, and for sure I love streams (I thought about this at the very beginning), but I see one problem: SassDoc is not about a single file input and output. We have an input directory, and an output directory too. Well I don't know how to stream directories, neither I know how this is handled with Gulp, so I don't really see what kind of stream we should pass to documentize instead of just directory names.

Also, still about your comment in #97, I don't see the interest in exposing the assets path. There's nothing ensuring a theme have an assets directory at all, but I would like to understand how this can help in Gulp!

---

Anyway, this would leads us to a 3 layers system:

1. Grab the data (SassDoc)
2. Transform the data (new)
3. Display the data (theme)

The question about the data transformation is: should we ensure a common data transformation (Markdown, groups, etc) for any theme (to force all themes to implement these features), or make the raw data the only link between SassDoc and a theme, letting the theme decide if it wants to group items or not, parse stuff as Markdown and so on?

[FWeinb]

There a two levels of transforming the data.

1. Resolve linking (like require/see)
2. preparing for the theme (markdown etc.)

The first one should be handled by sassdoc.

[nschonni]

It seems like you might get some insight by looking at (or just leveraging) @assemble as they've gone down the plug-in path before with a similar problem set

[FWeinb]

I implemented the new plugin interface here: https://github.com/SassDoc/sassdoc/tree/better-annoation-plugin

We have the ability to have three different key for each annotation now:

module.exports = {
  // This method is called to parse the annotation
  parse : function () {

  },

  // Return the default value if the annotation isn't used.
  default : function(){

  },

  // This method is called after all annotations are  parsed
  resolve : function ( flat ) {
  }
}

[KittyGiraudel]

You have a tremendous work Fabrice. Are we able to merge this into develop maybe?

[valeriangalliat]

This issue is related, we should remove Markdown parsing from the core and make it part of a sassdoc-filter project used by the views to support Markdown and other data processing stuff.

[KittyGiraudel]

Where are we with sassdoc-filter folks? :)

[valeriangalliat]

I'm planning to write the Markdown filter this week-end.

[KittyGiraudel]

Excellent. Keep us updated on tlk.io/sassdoc. ;)

[KittyGiraudel]

So what's up on this one? Can we close? Can we precise things?

[valeriangalliat]

Everything looks okay with sassdoc-index and sassdoc-filter. I think we can close.