Explaining commands and positional arguments with --docopt - command-line

Question

This is the example from docopt.org:
Naval Fate.
Usage:
naval_fate ship new <name>...
naval_fate ship <name> move <x> <y> [--speed=<kn>]
naval_fate ship shoot <x> <y>
naval_fate mine (set|remove) <x> <y> [--moored|--drifting]
naval_fate -h | --help
naval_fate --version
Options:
-h --help Show this screen.
--version Show version.
--speed=<kn> Speed in knots [default: 10].
--moored Moored (anchored) mine.
--drifting Drifting mine.
I see that options can have a long explanation in the Options: section. For example, it's very clear that naval_fate --version is to Show version.
However, is there a way to provide an extended explanation for commands or positional arguments? For example, how does the user know what naval_fate ship shoot <x> <y> does?

Answer 1

I arrived here with the same question, and I think I've figured out a solution.
The docopt docstring parser isn't very clever or rigorous, which is a good thing, as it means you can put all kinds of other information in your docstring without confusing docopt. For example, there's nothing to stop you adding Commands: or Arguments: sections to your docstring. Here's the docstring for the project I'm currently working on:
"""Helioplot.
Retrieve and plot heliometer results.
Usage:
helioplot fetch <root_dir_path> --host=<host> --password=<password> [--port=<port>] [--database=<database>] [--username=<username>]
Commands:
fetch <root_dir_path> Fetch and dump data into the directory specified
by <root_dir_path>.
Options:
-h --help Show this screen.
--version Show version.
--host=<host> The address of the computer hosting the database
--port=<port> The port number on which the database can be
accessed.
--database=<database> The name of the database.
--username=<username> A database username.
--password=<password> The database password.
"""