WIP - help refactor #288
WIP - help refactor #288
Conversation
- Slim down `chocolatey help` - Implement `chocolatey install help`
|
I really think that this is a good idea! The only concern that I would have would be keeping what is in the "help" in source, in sync with the "help" on the wiki. I mentioned this to @mwrock in a previous commit that I saw him doing where he had to manually update a synopsis on the wiki to match a change to the synopsis in the code. Is there any way to have "one source of truth", i.e. that we store the help documentation and synopsis information in one place, e.g. in the source code repo, and then flow this through into the wiki. That way you update once, and it is correct in both places? Just a thought... |
|
On the nu project, one of our committers was able to pull and display the text from the wiki pages for help commands. It was pretty neat, but it requires that you are online. |
|
Hmm, that isn't bad actually, and not unlike other systems, for instance, PowerShell itself with it's Update-Help option. Would it make sense to use the wiki as the "one source of truth" and then have Chocolatey download and cache the help files locally? Thoughts? |
|
That sounds pretty interesting. We'll start somewhere though with this and work towards something like that. |
|
gep13 I like that idea A LOT https://github.com/blog/699-making-github-more-open-git-backed-wikis As an alternate idea- |
|
@rismoney The more I think about this, the more I like it. Will add it to my ever growing list of things to look into :-) |
|
So what do you think I keep going in the same direction for now? It's close to the git model, will be an improvement, and you can consider caching wiki pages and rendering markdown in the console later ;) |
|
As an experiment, i think it would be good to know that we can load a file from file system and render as help text when requested. I don't see why we couldn't do this though. But yes, i think for now, that is the plan. Gary Sent from my Windows Phone From: corkupinemailto:[email protected] So what do you think I keep going in the same direction for now? It's close to the git model, will be an improvement, and you can consider caching wiki pages and rendering markdown in the console later ;) Reply to this email directly or view it on GitHub: |
|
Or, as a half way house, how about the following... Continue with what you are currently doing, but rather than put the help documentation directly in the PowerShell script, move it into a separate file, one file for each method. Then, when requested, read that line, and display to user. With that in place, we can then look to update those files, based on what is in the wiki, using something like a Update-Help method. Thoughts? Sent from my Windows Phone From: corkupinemailto:[email protected] So what do you think I keep going in the same direction for now? It's close to the git model, will be an improvement, and you can consider caching wiki pages and rendering markdown in the console later ;) Reply to this email directly or view it on GitHub: |
|
@ferventcoder I guess this relies on you being a stand up, all around good guy! Oh, wait... :-) I think this should be for any edit on the comment, regardless of who made the edit. |
|
@gep13 Separate files it is. My availability is pretty well saturated with work, so will get to it as I can. |
|
I hear that. Separate files is awesome, but what is the standard naming convention for the files? |
|
What about something like: Help-<Function Name>.txt i.e. Help-Chocolatey-Install.txt |
|
There is a convention for powershell for help file naming. Perhaps we should look it up? |
|
Ah, I see what you are getting at. My bad! |
Made
chocolatey helpmuch slimmer, and basically pointed tochocolatey [command] help. Implementedchocolatey install helpto see if this approach will be satisfactory.Also...yeah...it's still messy w/ comments and junk. I'll clean that up.
Ref #281