Add documentation for all commands

[NoahGorny]

I'm wondering whether we want to include this in the documentation. I've checked the main README file, it currently does not provide a complete list of all commands (e.g. bash-it reload). We might want to add that at one point - probably as a separate PR when (hopefully at one point) rework the documentation.

Originally posted by @nwinkler in https://github.com/Bash-it/bash-it/pull/1672#issuecomment-709528853

[tbhaxor]

There are so many commands. Well making a proper markdown for each command should be done in docs folder and then use it to serve documentation on readthedocs.io

[NoahGorny]

I guess it is a possible solution, although we already cover some of the commands in the readme.md. I want the easiest and cleanest way we can do it

[ahmadassaf]

As part of the discussion to happen in https://github.com/Bash-it/bash-it/issues/1678 I have both composure about descriptions and bashdoc annotations. For example, running a bash-it help plugins all (a new helper I added to show about descriptions for all enabled plugins + core functions) will print:

bash-it:core
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
_bash-it-backup                              backs up enabled components (plugins, aliases, completions)
_bash-it-describe                            describes bash-it components by listing the component, description and its status (enabled vs. disabled)
_bash-it-disable                             disable a bash-it component (plugin, component, alias)
_bash-it-doctor                              reloads a profile file with a BASH_IT_LOG_LEVEL set
_bash-it-enable                              enable a bash-it component (plugin, component, alias)
_bash-it-grep                                outputs a full path of the grep found on the filesystem
_bash-it-reload                              reloads the bash profile that corresponds to the correct OS type (.bashrc, .bash_profile)
_bash-it-restore                             restores enabled components (plugins, aliases, completions)
_bash-it-show                                list available bash_it components or allow filtering for a specific type e.g., plugins, aliases, completions
_bash-it-update                              updates the bash-it installation by fetching latest code from the remote git
_bash-it-version                             shows current bash-it version with the Current git SHA and commit hash

bash-it:core:cache
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
_bash-it-component-cache-add                 gets the component cache path in the /tmp directory
_bash-it-component-cache-clean               caches the component view in the /tmp directory

bash-it:core:components
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
__check-function-parameters                  check the passed parameter to make sure its valid and matches a component type
_bash-it-component-help                      show the about description for a component
_bash-it-component-item-is-disabled          checks if a given item is disabled for a particular component/file-type
_bash-it-component-item-is-enabled           checks if a given item is enabled for a particular component/file-type
_bash-it-component-list                      returns a list of items within each component (plugin, alias, completion)
_bash-it-component-list-disabled             returns a list of disabled items within each component (plugin, alias, completion)
_bash-it-component-list-enabled              returns a list of enabled items within each component (plugin, alias, completion)
_bash-it-component-list-matching             returns a list of items within each component (plugin, alias, completion) that match a string 
_bash-it-pluralize-component                 pluralize component name for consistency especially for search
_bash-it-singularize-component               singularize component name for consistency especially for search

bash-it:core:help
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
_help-aliases                                shows help for all aliases, or a specific alias group
_help-completions                            summarize all completions available in bash-it
_help-plugins                                summarize all functions defined by enabled bash-it plugins

bash-it:core:utils
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
_array-contains                              searches an array for an exact match against the term passed as the first argument to the function
_array-dedupe                                creates a concatenated array of unique and sorted elements
_clean-string                                cleans a string from whitespace give a passed cleaning mode
_command_exists                              check if the command passed as the argument exists
_is_function                                 check if the passed parameter is a function
_read_input                                  reads input from the prompt for a yes/no (one character) input

bash-it:log
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
_bash-it-get-component-name-from-path        get a component name from a component path
_bash-it-get-component-type-from-path        get a component type from a component path in a singular form (alias, plugin, completion)
_log_component                               log a component loading message by echoing to the screen the name and type
_log_debug                                   log a debug message by echoing to the screen
_log_error                                   log an error message by echoing to the screen
_log_general                                 internal function used for logging, uses BASH_IT_LOG_PREFIX as a prefix
_log_warning                                 log a warning message by echoing to the screen

bash-it:search
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
_bash-it-component-term-matches-negation     matches the negation of the search term entered
_bash-it-search                              searches for given terms amongst bash-it plugins, aliases and completions
_bash-it-search-component                    searches for given terms amongst a given component

[nwinkler]

Thanks - good thoughts, all!

The composure documentation of the functions is great, although it only provides help for the actual functions (with the underscore prefix). We should definitely add that, but it's only one option. Some more thoughts:

• The README file is already crowded as it is. It needs some major rework.
• I had thought about adding more documentation to the repo's Wiki instead of the README.
• @tbhaxor's suggestion about generating the documentation is great - potentially we could generate the Wiki from that documentation.
• We already have a bash-it help command, but it does not go into detail on each subcommand. How about adding support for things like bash-it help reload. The documentation could be sourced from @ahmadassaf's about documentation.

Thoughts?

[tbhaxor]

I guess it is a possible solution, although we already cover some of the commands in the readme.md. I want the easiest and cleanest way we can do it

Then i would ask you to go for readthedocs.io as it support in document searching also

[cornfeedhobo]

Great thoughts everyone :smiley:

My votes:

• use generation of some kind (composure is probably not enough)
• preferably include an enumerated list of functions and aliases found in each file, possibly with annotation parsing for documenting them
• break up the documentation as the readme is already big
• no preference on readthedocs vs wiki, but only use one

[NoahGorny]

This issue is something that I am looking into right now, really want to improve our docs

[gaelicWizard]

I'd like to suggest something like shocco for file-level comments/documentation. I'm a huge fan of "literate programming" for code-level documentation as the documentation is in the code! Single source of truth, harder to forget to update, easier to refer to when coding, &c.

(Not-code-level documentation should be separate, or the code gets unreadable. I've made that mistake in other projects.)