feat: plugin documentation callback support 🎉

[Stratus3D]

Summary

• Add support for an optional help callback scripts for plugins
• Document the required behavior for the help callback scripts on the create plugins page
• Write basic unit tests for the new code

Fixes: #512

[jthegedus]

I'll give this a test over the next 48hrs with a plugin.

Externally sourced data is going to be tricky to format well (80 char linewrap or columns etc). The only solution to this would be where we get control of parsing the content before writing to STDOUT, and in that we could either capture (redirect) the output from the plugin or provide variables for the plugin to populate which we would then print.

I raise this now (though we can certainly iterate on this) because I would like to address output to both STD OUT/ERR across the board for 0.9.0 milestone (I'll create all the issues and milestone for this tomorrow)

[Stratus3D]

@jthegedus yes that is one of my concerns with this. The output is so open ended that even if all plugins comply with the requirements I've specified here there will still be variations between plugins. I don't think this is ideal.

One alternative solution would be to have multiple callbacks for each kind of help for each plugin. So we could have a callback named bin/help.overview, bin/help.deps, bin/help.config, bin/help.links, etc... Then asdf core would be free to use (or ignore if needed) the output from these scripts in whatever way we deem best. And the scripts themselves would output to STDOUT with minimal formatting. The downside is that we could have to call and support more callbacks (and allow for missing callbacks as not every plugin would need them all). Perhaps this is kind of how man pages work? I've not looked into how they are organized, but this seems like it might be similar (with the exception that these are executable scripts that can vary their output based on the environment).

[Stratus3D]

I'm open to whatever everything thinks is best. I only wrote this code today and haven't used it extensively on my own, so I'll try to get more experience with this feature before proceeding with anything.

[jthegedus]

I like that our plugin interface for commands requires a specific format, and that we capture the output from the plugins and parse them ourselves in the core to STDOUT. Perhaps we can apply the same thing here requiring specific formats for each type of documentation?

• bin/help.overview is freeform text. We will take this and print to 80 cols
• bin/help.deps is a newline or space separated list (like asdf list all) which we render as a column of data
• bin/help.config what type of format would we expect people to use here?
• bin/help.links same as bin/help.deps

What are your thoughts on this?

Whether this would be implemented as separate callbacks is another question. It is perhaps better to separate them so the output can be format in a more distinct way. IF they were separate and optional, would we notify the users at all or just skip as we do now? (I'm just trying to consider the feedback we're getting regarding exit codes and our use of stderr and if this is something users would like to know at all. IE is the absence of bin/help.deps indicative of no deps, or just the absence of the plugin author to document the deps?)

Re man pages: I am also unsure how they work and perhaps it is time I learned 😅

I don't want to hold up the work being done here, but realise changing our plugin API later may cause issues and it may be easier to address these now (though we're pre 1.0 so that's part of the semver contract)

[Stratus3D]

Perhaps we can apply the same thing here requiring specific formats for each type of documentation?

bin/help.overview is freeform text. We will take this and print to 80 cols
bin/help.deps is a newline or space separated list (like asdf list all) which we render as a column of data

A single column of data representing package names? like:

coreutils
libxslt
...

This may be too restrictive. Sometimes dependencies may need to be available in OS package managers, and some package managers may lack certain packages, so some instructions on manually installation of dependencies may be needed occasionally. I guess we could make things work if each line of output represented only one dependency.

bin/help.config what type of format would we expect people to use here?

I think this would have to be freeform as well. Configuration instructions will vary greatly between tools and operating systems. Instructions may include setting environment variables, creating/editing config files, etc... To much to enforce a strict structure on the output.

bin/help.links same as bin/help.deps

This can be one link per line. Formats could be:

Link to API docs: http://somedomain.com/with/docs/
Another Link: http://someotherdomain.com/

Or:

http://somedomain.com/with/docs/
http://someotherdomain.com/

Even with both formats it should give us enough control over the final output.

[Stratus3D]

Whether this would be implemented as separate callbacks is another question. It is perhaps better to separate them so the output can be format in a more distinct way. IF they were separate and optional, would we notify the users at all or just skip as we do now?

I think the callbacks should be separate and optional. I think if say the bin/help.overview callback were missing we would just report that documentation for the plugin is not available and not look for any additional callbacks.

(I'm just trying to consider the feedback we're getting regarding exit codes and our use of stderr and if this is something users would like to know at all. IE is the absence of bin/help.deps indicative of no deps, or just the absence of the plugin author to document the deps?)

Not certain, but I guess perhaps that should indicate no deps? I think plugin authors should either implement all needed callbacks for help, or none of them at all.

[Stratus3D]

@jthegedus I found this answer about man pages helpful - https://unix.stackexchange.com/a/3587/74959

Working on this again today. Hopefully will get everything updated in a couple hours.

[Stratus3D]

@jthegedus the code has been updated based on our discussion. I may write some additional unit tests later today, but either way the code is ready for you to review again.

[jthegedus]

Yes!

[jthegedus]

This looks great! Awesome work