Fold documentation-readme into main cli?

[anandthakker]

Going along with the work in #236, should documentation-readme become documentation readme? @tmcw

[tmcw]

Yep, I think this makes sense.

[jfirebaugh]

Agreed about documentation readme being the ideal CLI syntax. Is there some way we can support command plugins, so that not all possible CLI functionality has to be baked in?

[anandthakker]

@jfirebaugh I like that notion.

As an initial take on the approach: maybe each command plugin is just a module that exports (a) a function accepting a reference to the main documentation module and some options, and (b) a short description. Then it's pretty straightforward for the main documentation cli can fairly easily display it as an option in the top-level help, and delegate to it with its (parsed) subargs.

"Core" commands, like build, can be baked in as local (internal) modules; others, like readme, can be a separate npm package pulled in as a dependency.

[jfirebaugh]

That sounds good. The open question in my mind is how registration of command plugins would work. Will documentation have a dependency on every command plugin? That doesn't seem scalable. If not, how does it obtain the list of currently installed plugins? Given any particular command documentation foo it could try requiring documentation-foo, but how would it know to display foo as an option in the top-level help when no subcommand is provided?

[anandthakker]

Yeah, I was stumped on the registration issue too. My instinct is that the
"right" approach to registration depends a lot on the nature of the plugin
ecosystem: if it start to become super diverse and dynamic, then it will
become worth it to invest in the discovery problem. Until then, I think we
can get by with (a) a few commands that ship as dependencies (like
documentation-readme), and (b) a hardcoded list of "known" installable
plugins which we can attempt to require.

On Fri, Dec 4, 2015 at 11:26 AM John Firebaugh notifications@github.com
wrote:

That sounds good. The open question in my mind is how registration of
command plugins would work. Will documentation have a dependency on every
command plugin? That doesn't seem scalable. If not, how does it obtain the
list of currently installed plugins? Given any particular command documentation
foo it could try requiring documentation-foo, but how would it know to
display foo as an option in the top-level help when no subcommand is
provided?

—
Reply to this email directly or view it on GitHub
#261 (comment)
.

[tmcw]

I'm kind of ¯_(ツ)_/¯ on installable cli plugins, given the low'ish number of plugins off the bat and the weirdness of implementing this with requires, it seems like we should get it done first and refactor later if we have ideas for what the next 5 plugins should be.

[anandthakker]

Yeah, agreed -- meant installable plugins bit just as a plausible future
bridge we can cross when we come to it

On Fri, Dec 4, 2015 at 2:55 PM Tom MacWright notifications@github.com
wrote:

I'm kind of ¯_(ツ)_/¯ on installable cli plugins, given the low'ish number
of plugins off the bat and the weirdness of implementing this with
requires, it seems like we should get it done first and refactor later if
we have ideas for what the next 5 plugins should be.

—
Reply to this email directly or view it on GitHub
#261 (comment)
.

[jfirebaugh]

👍

[anandthakker]

@tmcw do you see any reason to keep documentation-readme in its own repo or npm package? My inclination would be to fold the code in here as well -- #277 means we could keep it separate, but I don't really see a good reason to...