On Jan 28, 2013, at 3:05 PM, Nomi Harris <[email protected]> wrote:
I added brief text and a link to https://trac.kbase.us/projects/kbase/wiki/UserManuals explaining that if you follow the standard for your help message, then your help text will be harvested as part of the release process and made into a man page for your script. Right now, that's at the bottom of the User Manuals page--should it be made more prominent? Are we going to discourage people from hand-writing user manuals and encourage them to write good help messages instead?
I still think that a user manual should be developed manually. Command help messages are just that. They don't necessarily give a good overview or an indication of where to start. User manuals can be a lot more interactive, primarily through hypertext, and can also be used to give uninitiated users or those uncomfortable with running Unix commands in the first place a better place to start.
Yes, we need that. Maybe you could put up an initial straw-man page for that, Shiran?
I'll draft that up tomorrow as time allows. Bob, it would be great if you can review it to make sure I don't misspeak.
Agreed. Thanks for being proactive about this. Are there other discussions that we should put on the wiki?
Good question. The discussion on standardizing RPC exceptions comes to mind. Maybe we should have a wiki page for that. I'll do that to when I get the chance. Shiran
Nomi
Shiran
[1] (cf. emails from last week I can't link to because this is not a wiki)
On Jan 25, 2013, at 12:56 PM, Thomas Brettin <[email protected]> wrote:
Hi everyone.
In the note from Adam on Wednesday, this statement is made:
Command line scripts. All command line scripts need to be accessible from IRIS. If you are not creating command line scripts for your module, we need to know this and why. Tom will talk on the devel con call today what is required for integration into IRIS.
In order for us to accomplish this, module owners will need to ensure the following:
Script Documentation 1) that all commands return zero when invoked with the -h and the --help options. 2) that all commands print to standard out a help message when invoked with the -h and --help options. 3) that the output contains the following information (see template below) a description of what the script does a description of the parameters a description of the inputs and outputs
We'll harvest this text as part of the release process (see below)
Naming Convention We will be cleaning up the namespace soon as a single, comprehensive effort in the near future. To help, you can start now by following this simple guidance:
1) commands are named lowercase with a consistent use of underscores (or dashes). 2) the kb prefix will be dropped in future releases 3) prefix with a module identifier
examples are :
Auxiliary Store: as_create_index as_list_nodes as_resources as_create_node as_list_users as_view_node as_create_user as_modify_node as_view_user
Workspace Service (drop the kb): kbws-createws kbws-load kbws-types.pl kbws-delete kbws-login kbws-url kbws-deletews kbws-logout kbws-whoami kbws-exists kbws-meta kbws-workspace
Testing The use of the test-scripts target will become a mandatory requirement for scripts that will be executed within IRIS. Because we will have hundreds of commands, we need an automated way to at a minimum verify that the script will run (this verifies the deployment was done correctly and all runtime dependancies are in place). As a minimal start, you should write a shell script that.
1) invokes the script using pre-staged test data 2) verifies correct output. 3) verifies the correct exit code 4) one directory per test 5) this directory contains the input data and output to be compared against by way of a diff or something of your choice. 6) these test directories are located under the top level script-tests directory as per the standard laid out in the module.Makefile template.
Complex Commands Commands with complex interfaces, such as jnomics and the assembly service needs to be wrapped into simpler scripts for the user that set preset parameter values and turn the command/subcommand style interface into just a command interface.
Commands running on the IRIS host Those commands that themselves are not clients in a client-server architecture, that is commands that will execute on the IRIS host (matR comes to mind), need to have communicated to the release engineering team cpu, memory and storage requirements.
Release Process What I will do is modify the release process so that all commands are checked for the -h and --help options. The process will go something like first check to see if the -h and --help options exist and the command returns 0, for those that pass this check we'll have someone take a look at the output to see if it addresses the items in #3. The output will be saved as plain text, moved to the webroot directory under the deployment target, and from there be brought into the kbase.us/developer_zone site as html docs.
Here is the template:
NAME commandname -- one line summary of what it does
SYNOPSIS commandname [list of options]
DESCRIPTION Few sentences to paragraphs describing what the command does
A detailed description of the inputs
A detailed description of the outputs
name of parameter 1 - description of parameter (one parameter per line)
name of parameter 2 - description of parameter 2 (etc.)
EXAMPLES An example or two of how to call the command and what it would do
SEE ALSO List any related commands
AUTHORS Make yourself (and your coauthors) famous
NAME kbws-meta -- displays the metadata for the currently selected workspace
SYNOPSIS kbws-meta [-we]
DESCRIPTION Workspaces are used in KBase to provide an online location for all data, models, and analysis results. kbws-meta displays the metadata (for example, the date last modified and the permission settings) of the currently selected workspace (or the workspace specified on the command line with the "-w/--workspace" option).
Inputs: none
Outputs: metadata fields and values printed to stdout, one per line
Options: -w,--workspace ID of workspace you want to look at -e,--showerror Set to 1 to show any errors in execution
EXAMPLES $ kbws-meta Workspace ID: test Owner: chenry Moddate: 2012-12-26T06:11:50 Objects: 4 User permission: r Global permission:r
SEE ALSO kbws-list kbws-workspace kbws-listobj
AUTHORS Chris Henry
Thomas Brettin 865-603-7760 (cell) [email protected]