Add ability to order items by @access #239

Closed
Undistraction opened this Issue Oct 5, 2014 · 35 comments

Comments

Projects
None yet
5 participants
@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.

@HugoGiraudel

This comment has been minimized.

Show comment
Hide comment
@HugoGiraudel

HugoGiraudel Oct 5, 2014

Member

Current ordering is done as is:

  • Groups
  • Types
  • Filenames
  • Positions in the file
Member

HugoGiraudel commented Oct 5, 2014

Current ordering is done as is:

  • Groups
  • Types
  • Filenames
  • Positions in the file
@Undistraction

This comment has been minimized.

Show comment
Hide comment
@Undistraction

Undistraction Oct 5, 2014

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.

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.

@HugoGiraudel

This comment has been minimized.

Show comment
Hide comment
@HugoGiraudel

HugoGiraudel Oct 5, 2014

Member

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

Member

HugoGiraudel commented Oct 5, 2014

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

@valeriangalliat

This comment has been minimized.

Show comment
Hide comment
@valeriangalliat

valeriangalliat Oct 6, 2014

Member

+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.

Member

valeriangalliat commented Oct 6, 2014

+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

This comment has been minimized.

Show comment
Hide comment
@Undistraction

Undistraction Oct 6, 2014

@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.

@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.

@HugoGiraudel

This comment has been minimized.

Show comment
Hide comment
@HugoGiraudel

HugoGiraudel Oct 6, 2014

Member

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.

Member

HugoGiraudel commented Oct 6, 2014

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

This comment has been minimized.

Show comment
Hide comment
@valeriangalliat

valeriangalliat Oct 6, 2014

Member

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.

Member

valeriangalliat commented Oct 6, 2014

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.

@HugoGiraudel

This comment has been minimized.

Show comment
Hide comment
@HugoGiraudel

HugoGiraudel Oct 6, 2014

Member

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

Member

HugoGiraudel commented Oct 6, 2014

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

@valeriangalliat

This comment has been minimized.

Show comment
Hide comment
@valeriangalliat

valeriangalliat Oct 6, 2014

Member

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

Member

valeriangalliat commented Oct 6, 2014

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

@HugoGiraudel HugoGiraudel added the Feature label Oct 7, 2014

@HugoGiraudel HugoGiraudel modified the milestone: 2.1 Oct 9, 2014

@Undistraction

This comment has been minimized.

Show comment
Hide comment
@Undistraction

Undistraction Oct 10, 2014

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?

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?

@HugoGiraudel

This comment has been minimized.

Show comment
Hide comment
@HugoGiraudel

HugoGiraudel Oct 10, 2014

Member

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

sassdoc src dest --config .sassdocrc
Member

HugoGiraudel commented Oct 10, 2014

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

sassdoc src dest --config .sassdocrc
@Undistraction

This comment has been minimized.

Show comment
Hide comment
@Undistraction

Undistraction Oct 10, 2014

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

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

@HugoGiraudel

This comment has been minimized.

Show comment
Hide comment
@HugoGiraudel

HugoGiraudel Oct 10, 2014

Member

That is weird because groups are ordered by slugs.

Member

HugoGiraudel commented Oct 10, 2014

That is weird because groups are ordered by slugs.

@Undistraction

This comment has been minimized.

Show comment
Hide comment
@Undistraction

Undistraction Oct 10, 2014

@HugoGiraudel What is the correct syntax to define the order of groups to be API then Private and have all entities with an undefined group belong to the Private group?

@HugoGiraudel What is the correct syntax to define the order of groups to be API then Private and have all entities with an undefined group belong to the Private group?

@HugoGiraudel

This comment has been minimized.

Show comment
Hide comment
@HugoGiraudel

HugoGiraudel Oct 10, 2014

Member

This is not something you can do at the moment. But we are currently discussing your issue with @valeriangalliat.

Member

HugoGiraudel commented Oct 10, 2014

This is not something you can do at the moment. But we are currently discussing your issue with @valeriangalliat.

@Undistraction

This comment has been minimized.

Show comment
Hide comment
@Undistraction

Undistraction Oct 10, 2014

@HugoGiraudel Sorry, I must have misunderstood. When you listed the current ordering earlier it was:

  • Groups
  • Types
  • Filenames
  • Positions in the file

So I assumed that you meant Group names were used to order items, then types, then filenames etc.
So actually Groups aren't used for ordering at all? Or groups aren't used when you set a default group for items with an undefined group?

@HugoGiraudel Sorry, I must have misunderstood. When you listed the current ordering earlier it was:

  • Groups
  • Types
  • Filenames
  • Positions in the file

So I assumed that you meant Group names were used to order items, then types, then filenames etc.
So actually Groups aren't used for ordering at all? Or groups aren't used when you set a default group for items with an undefined group?

@HugoGiraudel

This comment has been minimized.

Show comment
Hide comment
@HugoGiraudel

HugoGiraudel Oct 10, 2014

Member

Groups are used. But you cannot define which group comes before which.

Member

HugoGiraudel commented Oct 10, 2014

Groups are used. But you cannot define which group comes before which.

@Undistraction

This comment has been minimized.

Show comment
Hide comment
@Undistraction

Undistraction Oct 10, 2014

OK. But they don't appear to be alphabetised either (API would come before Private).

OK. But they don't appear to be alphabetised either (API would come before Private).

@HugoGiraudel

This comment has been minimized.

Show comment
Hide comment
@HugoGiraudel

HugoGiraudel Oct 10, 2014

Member

I know. That's the weird thing.

Member

HugoGiraudel commented Oct 10, 2014

I know. That's the weird thing.

@valeriangalliat

This comment has been minimized.

Show comment
Hide comment
@valeriangalliat

valeriangalliat Oct 10, 2014

Member

Until 2.0 we can't sort by group first, actually it's type, then group.

But all API functions should be before private functions (and same for variable, mixins).

Member

valeriangalliat commented Oct 10, 2014

Until 2.0 we can't sort by group first, actually it's type, then group.

But all API functions should be before private functions (and same for variable, mixins).

@Undistraction

This comment has been minimized.

Show comment
Hide comment
@Undistraction

Undistraction Oct 10, 2014

Probably unrelated, but Sassdoc is also inexplicably downcasing the group name to api whilst leaving Private as titlecase.

Probably unrelated, but Sassdoc is also inexplicably downcasing the group name to api whilst leaving Private as titlecase.

@valeriangalliat

This comment has been minimized.

Show comment
Hide comment
@valeriangalliat

valeriangalliat Oct 10, 2014

Member

All group slugs are forced lowercase yeah. In your case it should be api: API, private: Private.
And it's sorted on the group slug, so api should come before private.

Member

valeriangalliat commented Oct 10, 2014

All group slugs are forced lowercase yeah. In your case it should be api: API, private: Private.
And it's sorted on the group slug, so api should come before private.

@Undistraction

This comment has been minimized.

Show comment
Hide comment
@Undistraction

Undistraction Oct 10, 2014

But not the name that is used in the config for entities without a defined group. Shall I open that as another issue? FWIW I think downcasing group names is a shame, but I understand why if you're using slugs directly.

But not the name that is used in the config for entities without a defined group. Shall I open that as another issue? FWIW I think downcasing group names is a shame, but I understand why if you're using slugs directly.

@HugoGiraudel

This comment has been minimized.

Show comment
Hide comment
@HugoGiraudel

HugoGiraudel Oct 10, 2014

Member

The group alias should stay as authored, yep. It's probably an issue at this point. I'm investigating.

Member

HugoGiraudel commented Oct 10, 2014

The group alias should stay as authored, yep. It's probably an issue at this point. I'm investigating.

@Undistraction

This comment has been minimized.

Show comment
Hide comment
@Undistraction

Undistraction Oct 10, 2014

OK. So the following gets me the right case in the docs, but still in the wrong order:

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

OK. So the following gets me the right case in the docs, but still in the wrong order:

  "groups": {
    "api": "API",
    "undefined": "Private"
  },
@HugoGiraudel

This comment has been minimized.

Show comment
Hide comment
@HugoGiraudel

HugoGiraudel Oct 10, 2014

Member

I cannot reproduce the case issue. Slugs are always lowercased, aliases are left as authored. Is it okay with you too?

Member

HugoGiraudel commented Oct 10, 2014

I cannot reproduce the case issue. Slugs are always lowercased, aliases are left as authored. Is it okay with you too?

@Undistraction

This comment has been minimized.

Show comment
Hide comment
@Undistraction

Undistraction Oct 10, 2014

See my previous answer. The initial problem was that I had used API:API, and because the API group had been lowercased by Sassdoc, this mapping failed and the original downcased group name was used.

However, this still doesn't explain why API is ordered after Private.

See my previous answer. The initial problem was that I had used API:API, and because the API group had been lowercased by Sassdoc, this mapping failed and the original downcased group name was used.

However, this still doesn't explain why API is ordered after Private.

@valeriangalliat

This comment has been minimized.

Show comment
Hide comment
@valeriangalliat

valeriangalliat Oct 10, 2014

Member

I just tried with the following file:

/**
 * @group API
 */
@function a() {}

/**
 *
 */
@function b() {}

/**
 * @group API
 */
@function c() {}

/**
 *
 */
@function d() {}
{
    "groups": {
        "api": "API",
        "undefined": "Private"
    }
}

Result:

Render result

Everything looks good to me here.

Member

valeriangalliat commented Oct 10, 2014

I just tried with the following file:

/**
 * @group API
 */
@function a() {}

/**
 *
 */
@function b() {}

/**
 * @group API
 */
@function c() {}

/**
 *
 */
@function d() {}
{
    "groups": {
        "api": "API",
        "undefined": "Private"
    }
}

Result:

Render result

Everything looks good to me here.

@HugoGiraudel HugoGiraudel changed the title from Allow ordering of documented entities by visibility to Add ability to order items by @access Nov 26, 2014

@pascalduez pascalduez removed their assignment Dec 3, 2014

@FWeinb

This comment has been minimized.

Show comment
Hide comment
@FWeinb

FWeinb Feb 8, 2015

Member

I think this should be solved by the default theme. The ordering of the data interface isn't defined in the API Spec of SassDoc and can change during minor or patch level updates. (It has already changed after the 2.0 release)

Moving this to the default theme is the right thing to do.

@SassDoc/owners Everyone ok with this?

Member

FWeinb commented Feb 8, 2015

I think this should be solved by the default theme. The ordering of the data interface isn't defined in the API Spec of SassDoc and can change during minor or patch level updates. (It has already changed after the 2.0 release)

Moving this to the default theme is the right thing to do.

@SassDoc/owners Everyone ok with this?

@HugoGiraudel

This comment has been minimized.

Show comment
Hide comment
@HugoGiraudel

HugoGiraudel Feb 8, 2015

Member

I don't see how the theme will manage to do so.

Member

HugoGiraudel commented Feb 8, 2015

I don't see how the theme will manage to do so.

@FWeinb

This comment has been minimized.

Show comment
Hide comment
@FWeinb

FWeinb Feb 8, 2015

Member

By doing it like this #239 (comment)

Member

FWeinb commented Feb 8, 2015

By doing it like this #239 (comment)

@valeriangalliat

This comment has been minimized.

Show comment
Hide comment
@valeriangalliat

valeriangalliat Feb 9, 2015

Member

There's no point in doing this in the default theme, if we want to sort by @access for everyone we do it in the core like the other sort criteria.

Doing it in the theme is only useful if you want a local behavior change.

Ideally the sort criteria should be configurable but it's still not the case.

Member

valeriangalliat commented Feb 9, 2015

There's no point in doing this in the default theme, if we want to sort by @access for everyone we do it in the core like the other sort criteria.

Doing it in the theme is only useful if you want a local behavior change.

Ideally the sort criteria should be configurable but it's still not the case.

@HugoGiraudel

This comment has been minimized.

Show comment
Hide comment
@HugoGiraudel

HugoGiraudel Feb 9, 2015

Member

My point, really.

Member

HugoGiraudel commented Feb 9, 2015

My point, really.

@pascalduez

This comment has been minimized.

Show comment
Hide comment
@pascalduez

pascalduez Feb 9, 2015

Member

And another sassdoc-extras filter ?
It's really handy to be able to choose which filters/sorting to apply or not in a theme by using or not the relative functions. Although if we do it in core it won't be op-out ?

If we want to foster diversity in themes, we should not do too much assumption upstream (core).

Member

pascalduez commented Feb 9, 2015

And another sassdoc-extras filter ?
It's really handy to be able to choose which filters/sorting to apply or not in a theme by using or not the relative functions. Although if we do it in core it won't be op-out ?

If we want to foster diversity in themes, we should not do too much assumption upstream (core).

@valeriangalliat

This comment has been minimized.

Show comment
Hide comment
@valeriangalliat

valeriangalliat Feb 9, 2015

Member

It's welcome as a filter, but the core still needs to sort the data so we have deterministic output.

Though, we need to think if we want the sort configuration to be at core's level or at the theme level… I think it would be acceptable if the default theme let users configure the sort order with a configuration option, but other themes could sort in a specific way using extras without letting users configure it. This way SassDoc core only cares about sorting for deterministic output, not user configuration.

Member

valeriangalliat commented Feb 9, 2015

It's welcome as a filter, but the core still needs to sort the data so we have deterministic output.

Though, we need to think if we want the sort configuration to be at core's level or at the theme level… I think it would be acceptable if the default theme let users configure the sort order with a configuration option, but other themes could sort in a specific way using extras without letting users configure it. This way SassDoc core only cares about sorting for deterministic output, not user configuration.

valeriangalliat added a commit to SassDoc/sassdoc-extras that referenced this issue Feb 13, 2015

Add a sort module
It's now possible for a theme using the sort extra to let users
configure the sort order.

Currently supported criteria are group, file, line and access.

The configuration is done with a `sort` context key. It's an array of
strings, representing a sort criteria plus an optional sort order. The
sort order is determined if the last character is either `>` or `<`
(respectively desc and asc).

Example:

    {
      "sort": [
        "access",
        "line>",
        "group",
        "file"
      ]
    }

* See SassDoc/sassdoc#239

valeriangalliat added a commit to SassDoc/sassdoc-extras that referenced this issue Feb 13, 2015

Add a sort module
It's now possible for a theme using the sort extra to let users
configure the sort order.

Currently supported criteria are group, file, line and access.

The configuration is done with a `sort` context key. It's an array of
strings, representing a sort criteria plus an optional sort order. The
sort order is determined if the last character is either `>` or `<`
(respectively desc and asc).

Example:

    {
      "sort": [
        "access",
        "line>",
        "group",
        "file"
      ]
    }

* See SassDoc/sassdoc#239

@valeriangalliat valeriangalliat referenced this issue in SassDoc/sassdoc-extras Feb 13, 2015

Merged

Add a sort module #17

valeriangalliat added a commit to SassDoc/sassdoc-theme-default that referenced this issue Feb 13, 2015

@valeriangalliat valeriangalliat referenced this issue in SassDoc/sassdoc-theme-default Feb 13, 2015

Merged

Add sort capability #69

valeriangalliat added a commit to SassDoc/sassdoc-theme-default that referenced this issue Feb 13, 2015

@pascalduez pascalduez closed this Feb 14, 2015

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment