Consider adding a debug option

[pascalduez]

After seeing issues like #309 #310 and obviously other ones in the past, we could benefit from adding a new -d --debug options.
This would not produce the final documentation but output useful information on the current environment. Either to stdout or in a sassdoc-debug.log.

• SassDoc version
• Node.js version
• npm version
• platform
• CLI location (either global or local)
• If CLI command run and options
• is a plugin used (Grunt, Gulp, ...)
• source path
• destination path
• CWD (maybe not useful for plugins?)
• environment (implies config)
• data

[KittyGiraudel]

I like that.

[valeriangalliat]

👍

Added CWD in your list.

[valeriangalliat]

is a plugin used (Grunt, Gulp, ...)

I don't understand. If --debug is a CLI option, plugins are not concerned, right?

[pascalduez]

I don't understand. If --debug is a CLI option, plugins are not concerned, right?

Good call... Would be interesting to be able to debug from plugins as well. Which means it should be a config option as well.

[valeriangalliat]

That's what I had in mind. I'll log some CLI-specific stuff in cli.js and the rest in sassdoc.js, and debug will be a config option (but ideally this config option should be settable from Grunt/Gulp command, like grunt --sassdoc-debug or something, without having to modify the *file).

[pascalduez]

grunt --sassdoc-debug that's not desirable.

What about env.debug = options['--debug'] in CLI ?

Also logging might be handy, but printing to a file would be a better option especially if we print the environment and/or data.

What I had in mind was to maybe use a stream (again).

[valeriangalliat]

No problem in CLI, I have already some helper to proxy command line arguments to configuration options.

About plugins, the only use case I see is:

• Run grunt;
• It fails;
• Run grunt --sassdoc-debug (or SASSDOC_DEBUG=1 grunt or whatever you can pass on CLI);
• Paste output in issue.

I don't think it's desirable to have to edit a file to enable debug mode (which is nearly always a temporary option), even for plugins.

[pascalduez]

I don't think it's desirable to have to edit a file to enable debug mode (which is nearly always a temporary option), even for plugins.

You won, good argumentation :-)

With Grunt it's fairly easy to pass arguments, not sure about the others. Especially because there's no more Gulp plugins anymore \o/.

[valeriangalliat]

Well for sure SASSDOC_DEBUG=1 grunt|gulp|any will work, since we can always access environment variables. 😄

So I'm not even setting this as a configuration option; I just take it from environment or CLI option. This implies there's literally nothing to update in the plugins, and I like it.

[pascalduez]

👍