search

alextremblay / phpIPAM-Scraper

A python library to retrieve device IPs from a phpIPAM installation
1 stars 0 forks source link

inline help improvement #3

Open gilcot opened 7 years ago

gilcot commented 7 years ago

Hello,

Currently, in interactive/shell use, when I type help it says:

Documented commands (type help ):

config get

Undocumented commands:

exit help quit

The command help can easily be documented so:

usage: help [command] or: command --help

Show usage of a command. Without any command, show this help

Documented commands: config For working with this tool's configuration help Showing this message get For retrieving information from phpIPAM

Undocumented commands: exit Ends interactive session quit Ends interactive session

Now, for config and get commands, there are some corrections needed. Let's look at the first one, when I issue a help config

Usage: config [OPTIONS] COMMAND [ARGS]...

Commands for working with this tool's stored configuration. Must be called with a subcommand.

Options: --help Show this message and exit.

Commands: get-url Show the currently configured phpIPAM URL to... set-url Specify a new phpIPAM URL for the tool to...

But, there's only one option and this one has precedence over everything. By then, config --help blah or just config --help gives the same result! Also, there's said that it "must be called with a subcommand.".. So, I suggest rewriting the help that way:

Usage: config SUBCOMMAND [URL] config --help

Subcommands for working with this tool's stored configuration.

--help Show this message and exit.

Subcommands: get-url Show the currently configured phpIPAM URL to... set-url Specify a new phpIPAM URL for the tool to...

Of course, the current presentation is not wrong, except there's only one option:

Usage: config [--help] SUBCOMMAND [URL]

Subcommands for working with this tool's stored configuration.

--help Show this message and exit.

Subcommands: get-url Show the currently configured phpIPAM URL to... set-url Specify a new phpIPAM URL for the tool to...

Better, we may avoid mentionning the common option everytime:

Usage: config SUBCOMMAND [URL]

Subcommands for working with this tool's stored configuration.

Subcommands: get-url Show the currently configured phpIPAM URL to... set-url Specify a new phpIPAM URL for the tool to...

Notice the use of URL instead of less explicit ARGS (and confusing too because there's only one) Same thing when issuing get --help or help get (here, use KEYWORD instead of ARGS...)

Usage: get SUBCOMMAND KEYWORD

Subcommands to retrieve info from phpIPAM. KEYWORD is a part of the hostname, case insensitive.

Subcommands: all Search all available sources in phpIPAM device Search the Devices page search Search the 'IP Addresses' list; KEYWORD may be begin of IP and star

Regards.

alextremblay commented 7 years ago

Hello again, thanks for the feedback!

the command-line interface for this application was made with a CLI framework that has a somewhat tricky help system. Ill play around with it when I get some time and see what I can do about making it more clear and concise.