Improve help text for admin commands

This commit is contained in:
Andrei Vasiliu 2022-01-21 11:06:16 +02:00
parent f244c0e2ce
commit cc3ef1a8be

View file

@ -147,6 +147,7 @@ impl Admin {
}
}
// Parse chat messages from the admin room into an AdminCommand object
pub fn parse_admin_command(db: &Database, command_line: &str, body: Vec<&str>) -> AdminCommand {
let mut argv: Vec<_> = command_line.split_whitespace().skip(1).collect();
@ -191,10 +192,13 @@ pub fn parse_admin_command(db: &Database, command_line: &str, body: Vec<&str>) -
#[derive(StructOpt)]
enum AdminCommands {
#[structopt(verbatim_doc_comment)]
/// Register a bridge using its registration YAML
/// Register an appservice using its registration YAML
///
/// This command needs a YAML generated by an appservice (such as a mautrix
/// bridge), which must be provided in a code-block below the command.
/// This command needs a YAML generated by an appservice (such as a bridge),
/// which must be provided in a Markdown code-block below the command.
///
/// Registering a new bridge using the ID of an existing bridge will replace
/// the old one.
///
/// Example:
/// ````
@ -204,16 +208,27 @@ enum AdminCommands {
/// ```
/// ````
RegisterAppservice,
/// Unregister a bridge using its ID
/// Unregister an appservice using its ID
///
/// You can find the ID using the `list-appservices` command.
UnregisterAppservice { appservice_identifier: String },
/// List all the currently registered bridges
/// List all the currently registered appservices
ListAppservices,
/// Get the auth_chain of a PDU
GetAuthChain { event_id: Box<EventId> },
/// Parse and print a PDU from a JSON
///
/// The PDU event is only checked for validity and is not added to the
/// database.
ParsePdu,
/// Retrieve and print a PDU by ID from the Conduit database
GetPdu { event_id: Box<EventId> },
/// Print database memory usage statistics
DatabaseMemoryUsage,
}
@ -365,6 +380,7 @@ pub fn try_parse_admin_command(
Ok(admin_command)
}
// Utility to turn structopt's `--help` text to markdown.
fn usage_to_markdown(text: &str) -> String {
// For the conduit admin room, subcommands become main commands
let text = text.replace("SUBCOMMAND", "COMMAND");
@ -390,6 +406,7 @@ fn usage_to_markdown(text: &str) -> String {
text.to_string()
}
// Convert markdown to HTML using the CommonMark flavor
fn markdown_to_html(text: &str) -> String {
// CommonMark's spec allows HTML tags; however, CLI required arguments look
// very much like tags so escape them.