Add ability to order items by @access

[Undistraction]

It appears that there is no way to control the ordering of public/private entities in the docs.

I have a few important mixins and a lot of (private) helper functions. Whilst I would like the private functions to appear in the docs, they currently appear before all the mixins which are the lib's API and much more important. I was hoping that the access item in the .sassdocrc would control the order as well as the visibility, but the order of items seems not to effect the order of the entities in the docs.

[KittyGiraudel]

Current ordering is done as is:

• Groups
• Types
• Filenames
• Positions in the file

[Undistraction]

Groups feels more like meta and types, filenames and position seem almost arbitrary. For some projects, the API will consist of mixins and for others it will consist of functions, or maybe a combination of both.

A developer needs a way of defining which entities take precedence, and it seems to me that the entirely artificial public/private is a good way to do this.

I think it would make sense to order based on:

• Groups
• Visibility (public | private)
• Types
• Filenames
• Positions in the file

I suppose Groups could be used to Group API and non-API, but it doesn't feel like this is what groups are for.

[KittyGiraudel]

I like the idea of sorting per visibility. @SassDoc/owners, any thought?

[valeriangalliat]

+1, we could add it in the default sorting.

But keep in mind it's possible to sort by whatever criteria you want with a custom theme.

[Undistraction]

@valeriangalliat Whilst I love the custom theming, on most of the projects I've worked on, getting decent documentation up and maintained was enough of a struggle and almost always (unfortunately) seems to be at the bottom of the list, and theming the docs is somewhere below that ;). I imagine you will find the vast majority of developers (many of whom will not be designers) will use the default theme, so I think the more control you can give them without needing to build a custom theme the better.

[KittyGiraudel]

I imagine you will find the vast majority of developers (many of whom will not be designers) will use the default theme, so I think the more control you can give them without needing to build a custom theme the better.

Agreed. Ordering has always been our pet peeve anyway.

[valeriangalliat]

I totally understand this, and that's why I like the idea to add this in the default sorting, or even add something to the .sassdocrc to define the keys to sort on.

Though, as a temporary fix, it's easy to create a custom theme decorating the default theme (yeah, that's the interesting part):

module.exports = function (dest, ctx) {
  ctx.data = sort(ctx.data);
  require('sassdoc-theme-light')(dest, ctx);
};

function sort(data) {
  // Custom sort
}

See sorter.js for a good example.

Though as said here, we're required to sort by type before anything else until 2.0 because of the data structure.

[KittyGiraudel]

What about adding an indexer by visibility in sassdoc-index?

[valeriangalliat]

Why not, but a new index would require to adapt the theme templates.

[Undistraction]

So can I use groups to control the order items are displayed in the docs? I've tried adding an @group API to all my public mixins and tried to control order in .sassdocrc using:

  "groups": {
    "API": "API",
    "undefined": "Private"
  },

But this still displays my private functions first, then my API group below. I can only find references in the docs to using this groups setting to set a group for undefined items. Can it also be used to control order?

[KittyGiraudel]

Silly question, do you correctly use your .sassdocrc file by using the --config flag when running sassdoc?

sassdoc src dest --config .sassdocrc

[Undistraction]

Yep. Everything else is working great. And the groups setting is working, because I can alter the group name for undefined.