Can the CLI be aware of custom annotations?

[tysongach]

I was looking at adding a custom annotation, but it seems that the SassDoc CLI does not parse them.

Upon further investigation, am I correct in that custom annotations are only parsed on the (custom) theme level?

For example, if I add a custom annotation for @awesome, and then run the CLI, I get an error:

sassdoc core/ --parse --verbose --strict

# returns
[ERROR] Parser for annotation `awesome` not found.

Is there a reason the CLI could not be aware of custom annotations, outputting them along with the rest of the data when parsing to JSON?

[pascalduez]

Hi,

if you added customs annotations, this means you have a custom theme at hand, so basically it's just about using the CLI --theme argument to point to it.

[tysongach]

Hi @pascalduez!

We actually aren’t using a custom theme, we’re just parsing to JSON then doing our own thing. So we were really just trying to get that custom annotation to be output into the JSON with the rest of the annotations.

[pascalduez]

I understand the need and also the possible frustration, but currently the only way to get custom annotations parsed is through a theme. That's why we didn't called them "plugins". There was particular reasons which led us the take that path.

As a workaround you don't necessarily need to build a full theme to make it work, just a total bare one with only one index.js. You need to tell SassDoc how to handle those annotations as described in the docs. Might looks a bit weird when you only want some JSON, but that's the fastest way to get something working for now...

[tysongach]

@pascalduez I can appreciate the restraint and wanting to keep SassDoc small and focused.

So, (using the custom annotation example from your website) can I just dump this into an index.js file?

module.exports.annotations.push({
  name: 'awesome',
  parse: function () { return true; },
  default: function (comment) { return false; },
  autofill: function (comment) {},
  multiple: false,
  alias: ['wow'],
});

[pascalduez]

I would need to dig a bit more into this to be sure. But it's worth giving it a quick try. Obviously the parse method of custom annotations will need to do more work or at least return something else than true :)
Have a look at the core ones for examples.

Other requirements:

• a package.json ?
• a function as default export

module.exports = function () {};

[KittyGiraudel]

I’m going to close this. :)