Add documentation page with the output of --help

[simonw]

Can be maintained using cog from #373. Similar in purpose to the API reference page, but this is for the CLI.

[simonw]

I'll call the new page "CLI reference", for consistency with the API reference page here: https://sqlite-utils.datasette.io/en/stable/reference.html

[simonw]

Here's the cog code I used:

sqlite-utils/docs/cli-reference.rst

Lines 11 to 76 in 1d44b0c

	.. [[[cog
	from sqlite_utils import cli
	from click.testing import CliRunner
	import textwrap
	commands = list(cli.cli.commands.keys())
	go_first = [
	"query", "memory", "insert", "upsert", "bulk", "search", "transform", "extract",
	"schema", "insert-files", "analyze-tables", "convert", "tables", "views", "rows",
	"triggers", "indexes", "create-database", "create-table", "create-index",
	"enable-fts", "populate-fts", "rebuild-fts", "disable-fts"
	]
	refs = {
	"query": "cli_query",
	"memory": "cli_memory",
	"insert": ["cli_inserting_data", "cli_insert_csv_tsv"],
	"upsert": "cli_upsert",
	"tables": "cli_tables",
	"views": "cli_views",
	"optimize": "cli_optimize",
	"rows": "cli_rows",
	"triggers": "cli_triggers",
	"indexes": "cli_indexes",
	"enable-fts": "cli_fts",
	"analyze": "cli_analyze",
	"vacuum": "cli_vacuum",
	"dump": "cli_dump",
	"add-column": "cli_add_column",
	"add-foreign-key": "cli_add_foreign_key",
	"add-foreign-keys": "cli_add_foreign_keys",
	"index-foreign-keys": "cli_index_foreign_keys",
	"create-index": "cli_create_index",
	"enable-wal": "cli_wal",
	"enable-counts": "cli_enable_counts",
	"bulk": "cli_bulk",
	"create-database": "cli_create_database",
	"create-table": "cli_create_table",
	"drop-table": "cli_drop_table",
	"create-view": "cli_create_view",
	"drop-view": "cli_drop_view",
	"search": "cli_search",
	"transform": "cli_transform_table",
	"extract": "cli_extract",
	"schema": "cli_schema",
	"insert-files": "cli_insert_files",
	"analyze-tables": "cli_analyze_tables",
	"convert": "cli_convert",
	}
	commands.sort(key = lambda command: go_first.index(command) if command in go_first else 999)
	for command in commands:
	cog.out(command + "\n")
	cog.out(("=" * len(command)) + "\n\n")
	if command in refs:
	command_refs = refs[command]
	if isinstance(command_refs, str):
	command_refs = [command_refs]
	cog.out(
	"See {}.\n\n".format(
	", ".join(":ref:`{}`".format(c) for c in command_refs)
	)
	)
	cog.out("::\n\n")
	result = CliRunner().invoke(cli.cli, [command, "--help"])
	output = result.output.replace("Usage: cli ", "Usage: sqlite-utils ")
	cog.out(textwrap.indent(output, ' '))
	cog.out("\n\n")
	.. ]]]

[simonw]

The new page of documentation: https://sqlite-utils.datasette.io/en/latest/cli-reference.html

[simonw]

Twitter thread about this: https://twitter.com/simonw/status/1481020195074293761