Shell Documentation

Commands are self documented by using annotations. These annotations are used to generate the base of the command documentation, like: short description, syntax, options, arguments etc. Using this information the shell automatically generates basic help for you.

The generated documentation is available in both text format (for terminal) and wiki format. See Nuxeo Shell Command Index for the wiki format.

This is the minimal documentation provided by any command and it may be enough for simple commands. But for more complex commands you may want to give more in depth instructions or examples. To do this you can create a text file that hase the same name as the short name of the command class plus the .help extension. This file must reside in the JAR in the same package as the command class.

Technical Detail

The help file class is located at runtime using the command class getResource method and the naming pattern specified above.

The help file is an ASCII text file which may contain some special tags to control the help rendering in both terminal or wiki mode. The most important tags are:

{header} - can be used to use a bold font for a title. Working in both terminal and wiki. Usage:
```
{header}EXAMPLES{header}
Here is an example of ...
```
{bold} - same as {header}.
{code} - can be used to escape code - working only in wiki, ignored (tag is removed) in terminal.

Also, you can use any confluence {tag}. It will be correctly displayed in the wiki and ignored in the terminal. There is also a set of tags that are working only in terminal:

underscore
blink
reverse
concealed

Color tags:

black
red
green
yellow
blue
magenta
cyan
white

Background tags:

bg.black
bg.red
bg.green
bg.yellow
bg.blue
bg.magenta
bg.cyan
bg.white

In addition you can also use any numeric control code as the tag name. See JLine documentation for more details on the terminal codes.

:warning: Anyway it is recommended to only use header, bold and other wiki tags like code since terminal tags are not translated in wiki tags.

Important

When contributing new commands in the Nuxeo Shell core library (or modifying old ones) please make sure you update the wiki at Nuxeo Shell Command Index.

Here are instructions on how to synchronize the wiki page with the modifications in Nuxeo Shell:

Export in wiki format the namespace you modified:
```
java -jar nuxeo-shell.jar -e "connect -u Administrator -p Administrator http://localhost:8080/nuxeo/site/automation; help -export tofile.wiki -ns remote"
```
The connect command is needed if you want to export the remote namespace. For local namespaces you doesn't need to connect to a server.
Copy/Paste the content of the exported wiki file to the Wiki Page under Nuxeo Shell Command Index corresponding to the updated namespace.