Opened 6 years ago

Last modified 6 years ago

#2654 assigned enhancement

Add subcommand documentation from bundles to doc index

Reported by: Tom Goddard Owned by: Greg Couch
Priority: moderate Milestone:
Component: Documentation Version:
Keywords: Cc: Conrad Huang, Elaine Meng
Blocked By: Blocking:
Notify when closed: Platform: all
Project: ChimeraX

Description

Currently command documentation in toolshed bundles is merged into the main ChimeraX command index, but only for top level commands. If a bundle adds a subcommand it does not get merged into any index. For instance, the RealSpace bundle adds the "device realspace" command. If the docs are put in the RealSpace bundle, they will not be seen if "help device" is used.

I don't have a clear an idea of how documentation for subcommands from bundles can be integrated. One idea is that all builtin commands have javascript to generate a subcommand index at the top of the main command page.

A related thought is that current documentation organization that puts all subcommands in one html page maybe should be changed to have subcommands each use a separate html page. Commands like volume and color with many subcommands have exceedingly long manual pages currently.

Change History (1)

in reply to:  1 ; comment:1 by Elaine Meng, 6 years ago

I would strongly lobby against having separate pages for subcommands, unless it is some kind of optional thing that a developer, say Tristan, can choose to do just for his bundle(s). Often the subcommands go together quite logically with the main command (e.g. deleting items created by the main command), so putting them in a separate page would require even more duplication of information, or a very high amount of making people follow several links just to understand the subcommand’s function.  Our documentation already has a pretty high number of separate pages, and it’s only going to increase.
Note: See TracTickets for help on using tickets.