From 76054a308fcaddeb21c8b05e0a1f58061218467e Mon Sep 17 00:00:00 2001 From: Jose Diaz-Gonzalez Date: Sat, 4 Apr 2020 16:43:31 -0400 Subject: [PATCH] docs: drop unimpemented commands from readme and reorganize --- README.md | 168 +++++++++++++++++------------------------------ bin/generate | 155 ++++++++++++++++++++++--------------------- subcommands/info | 2 +- 3 files changed, 141 insertions(+), 184 deletions(-) diff --git a/README.md b/README.md index ab78bcd..c217ccd 100644 --- a/README.md +++ b/README.md @@ -36,7 +36,7 @@ mongo:exists # check if the mongo service mongo:export # export a dump of the mongo service database mongo:expose # expose a mongo service on custom port if provided (random port otherwise) mongo:import # import a dump into the mongo service database -mongo:info [--single-info-flag] # print the connection information +mongo:info [--single-info-flag] # print the service information mongo:link [--link-flags...] # link the mongo service to the app mongo:linked # check if the mongo service is linked to an app mongo:links # list all apps linked to the mongo service @@ -56,20 +56,7 @@ mongo:upgrade [--upgrade-flags...] # upgrade service t Help for any commands can be displayed by specifying the command as an argument to mongo:help. Please consult the `mongo:help` command for any undocumented commands. ### Basic Usage -### list all mongo services -```shell -# usage -dokku mongo:list -``` - -examples: - -List all services: - -```shell -dokku mongo:list -``` ### create a mongo service ```shell @@ -77,15 +64,13 @@ dokku mongo:list dokku mongo:create [--create-flags...] ``` -examples: - Create a mongo service named lolipop: ```shell dokku mongo:create lolipop ``` -You can also specify the image and image version to use for the service. It *must* be compatible with the ${plugin_image} image. : +You can also specify the image and image version to use for the service. It *must* be compatible with the ${plugin_image} image. ```shell export MONGO_IMAGE="${PLUGIN_IMAGE}" @@ -93,21 +78,20 @@ export MONGO_IMAGE_VERSION="${PLUGIN_IMAGE_VERSION}" dokku mongo:create lolipop ``` -You can also specify custom environment variables to start the mongo service in semi-colon separated form. : +You can also specify custom environment variables to start the mongo service in semi-colon separated form. ```shell export MONGO_CUSTOM_ENV="USER=alpha;HOST=beta" dokku mongo:create lolipop ``` -### print the connection information + +### print the service information ```shell # usage dokku mongo:info [--single-info-flag] ``` -examples: - Get connection information as follows: ```shell @@ -128,6 +112,20 @@ dokku mongo:info lolipop --service-root dokku mongo:info lolipop --status dokku mongo:info lolipop --version ``` + +### list all mongo services + +```shell +# usage +dokku mongo:list +``` + +List all services: + +```shell +dokku mongo:list +``` + ### print the most recent log(s) for this service ```shell @@ -135,8 +133,6 @@ dokku mongo:info lolipop --version dokku mongo:logs [-t|--tail] ``` -examples: - You can tail logs for a particular service: ```shell @@ -148,6 +144,7 @@ By default, logs will not be tailed, but you can do this with the --tail flag: ```shell dokku mongo:logs lolipop --tail ``` + ### link the mongo service to the app ```shell @@ -155,9 +152,7 @@ dokku mongo:logs lolipop --tail dokku mongo:link [--link-flags...] ``` -examples: - -A mongo service can be linked to a container. This will use native docker links via the docker-options plugin. Here we link it to our 'playground' app. : +A mongo service can be linked to a container. This will use native docker links via the docker-options plugin. Here we link it to our 'playground' app. > NOTE: this will restart your app @@ -188,7 +183,7 @@ The host exposed here only works internally in docker containers. If you want yo dokku mongo:link other_service playground ``` -It is possible to change the protocol for mongo_url by setting the environment variable mongo_database_scheme on the app. Doing so will after linking will cause the plugin to think the service is not linked, and we advise you to unlink before proceeding. : +It is possible to change the protocol for mongo_url by setting the environment variable mongo_database_scheme on the app. Doing so will after linking will cause the plugin to think the service is not linked, and we advise you to unlink before proceeding. ```shell dokku config:set playground MONGO_DATABASE_SCHEME=mongodb2 @@ -200,6 +195,7 @@ This will cause mongo_url to be set as: ``` mongodb2://lolipop:SOME_PASSWORD@dokku-mongo-lolipop:27017/lolipop ``` + ### unlink the mongo service from the app ```shell @@ -207,8 +203,6 @@ mongodb2://lolipop:SOME_PASSWORD@dokku-mongo-lolipop:27017/lolipop dokku mongo:unlink ``` -examples: - You can unlink a mongo service: > NOTE: this will restart your app and unset related environment variables @@ -216,20 +210,6 @@ You can unlink a mongo service: ```shell dokku mongo:unlink lolipop playground ``` -### delete the mongo service/data/container if there are no links left - -```shell -# usage -dokku mongo:destroy [-f|--force] -``` - -examples: - -Destroy the service, it's data, and the running container: - -```shell -dokku mongo:destroy lolipop -``` ### Service Lifecycle @@ -242,13 +222,12 @@ The lifecycle of each service can be managed through the following commands: dokku mongo:connect ``` -examples: - Connect to the service via the mongo connection tool: ```shell dokku mongo:connect lolipop ``` + ### enter or run a command in a running mongo service container ```shell @@ -256,19 +235,18 @@ dokku mongo:connect lolipop dokku mongo:enter ``` -examples: - -A bash prompt can be opened against a running service. Filesystem changes will not be saved to disk. : +A bash prompt can be opened against a running service. Filesystem changes will not be saved to disk. ```shell dokku mongo:enter lolipop ``` -You may also run a command directly against the service. Filesystem changes will not be saved to disk. : +You may also run a command directly against the service. Filesystem changes will not be saved to disk. ```shell dokku mongo:enter lolipop touch /tmp/test ``` + ### expose a mongo service on custom port if provided (random port otherwise) ```shell @@ -276,13 +254,12 @@ dokku mongo:enter lolipop touch /tmp/test dokku mongo:expose ``` -examples: - Expose the service on the service's normal ports, allowing access to it from the public interface (0. 0. 0. 0): ```shell dokku mongo:expose lolipop ${PLUGIN_DATASTORE_PORTS[@]} ``` + ### unexpose a previously exposed mongo service ```shell @@ -290,13 +267,12 @@ dokku mongo:expose lolipop ${PLUGIN_DATASTORE_PORTS[@]} dokku mongo:unexpose ``` -examples: - Unexpose the service, removing access to it from the public interface (0. 0. 0. 0): ```shell dokku mongo:unexpose lolipop ``` + ### promote service as MONGO_URL in ```shell @@ -304,8 +280,6 @@ dokku mongo:unexpose lolipop dokku mongo:promote ``` -examples: - If you have a mongo service linked to an app and try to link another mongo service another link environment variable will be generated automatically: ``` @@ -327,20 +301,7 @@ MONGO_URL=mongodb://other_service:ANOTHER_PASSWORD@dokku-mongo-other-service:270 DOKKU_MONGO_BLUE_URL=mongodb://other_service:ANOTHER_PASSWORD@dokku-mongo-other-service:27017/other_service DOKKU_MONGO_SILVER_URL=mongodb://lolipop:SOME_PASSWORD@dokku-mongo-lolipop:27017/lolipop ``` -### graceful shutdown and restart of the mongo service container -```shell -# usage -dokku mongo:restart -``` - -examples: - -Restart the service: - -```shell -dokku mongo:restart lolipop -``` ### start a previously stopped mongo service ```shell @@ -348,13 +309,12 @@ dokku mongo:restart lolipop dokku mongo:start ``` -examples: - Start the service: ```shell dokku mongo:start lolipop ``` + ### stop a running mongo service ```shell @@ -362,13 +322,25 @@ dokku mongo:start lolipop dokku mongo:stop ``` -examples: - Stop the service and the running container: ```shell dokku mongo:stop lolipop ``` + +### graceful shutdown and restart of the mongo service container + +```shell +# usage +dokku mongo:restart +``` + +Restart the service: + +```shell +dokku mongo:restart lolipop +``` + ### upgrade service to the specified versions ```shell @@ -376,8 +348,6 @@ dokku mongo:stop lolipop dokku mongo:upgrade [--upgrade-flags...] ``` -examples: - You can upgrade an existing service to a new image or image-version: ```shell @@ -395,13 +365,12 @@ Service scripting can be executed using the following commands: dokku mongo:app-links ``` -examples: - -List all mongo services that are linked to the 'playground' app. : +List all mongo services that are linked to the 'playground' app. ```shell dokku mongo:app-links playground ``` + ### create container then copy data from into ```shell @@ -409,13 +378,12 @@ dokku mongo:app-links playground dokku mongo:clone [--clone-flags...] ``` -examples: - You can clone an existing service to a new one: ```shell dokku mongo:clone lolipop lolipop-2 ``` + ### check if the mongo service exists ```shell @@ -423,13 +391,12 @@ dokku mongo:clone lolipop lolipop-2 dokku mongo:exists ``` -examples: - -Here we check if the lolipop mongo service exists. : +Here we check if the lolipop mongo service exists. ```shell dokku mongo:exists lolipop ``` + ### check if the mongo service is linked to an app ```shell @@ -437,13 +404,12 @@ dokku mongo:exists lolipop dokku mongo:linked ``` -examples: - -Here we check if the lolipop mongo service is linked to the 'playground' app. : +Here we check if the lolipop mongo service is linked to the 'playground' app. ```shell dokku mongo:linked lolipop playground ``` + ### list all apps linked to the mongo service ```shell @@ -451,9 +417,7 @@ dokku mongo:linked lolipop playground dokku mongo:links ``` -examples: - -List all apps linked to the 'lolipop' mongo service. : +List all apps linked to the 'lolipop' mongo service. ```shell dokku mongo:links lolipop @@ -470,13 +434,12 @@ The underlying service data can be imported and exported with the following comm dokku mongo:import ``` -examples: - Import a datastore dump: ```shell dokku mongo:import lolipop < database.dump ``` + ### export a dump of the mongo service database ```shell @@ -484,8 +447,6 @@ dokku mongo:import lolipop < database.dump dokku mongo:export ``` -examples: - By default, datastore output is exported to stdout: ```shell @@ -513,8 +474,6 @@ Backups can be performed using the backup commands: dokku mongo:backup-auth ``` -examples: - Setup s3 backup authentication: ```shell @@ -538,6 +497,7 @@ More specific example for minio auth: ```shell dokku mongo:backup-auth lolipop MINIO_ACCESS_KEY_ID MINIO_SECRET_ACCESS_KEY us-east-1 s3v4 https://YOURMINIOSERVICE ``` + ### removes backup authentication for the mongo service ```shell @@ -545,13 +505,12 @@ dokku mongo:backup-auth lolipop MINIO_ACCESS_KEY_ID MINIO_SECRET_ACCESS_KEY us-e dokku mongo:backup-deauth ``` -examples: - Remove s3 authentication: ```shell dokku mongo:backup-deauth lolipop ``` + ### creates a backup of the mongo service to an existing s3 bucket ```shell @@ -559,13 +518,12 @@ dokku mongo:backup-deauth lolipop dokku mongo:backup [--use-iam] ``` -examples: - Backup the 'lolipop' service to the 'my-s3-bucket' bucket on aws: ```shell dokku mongo:backup lolipop my-s3-bucket --use-iam ``` + ### sets encryption for all future backups of mongo service ```shell @@ -573,13 +531,12 @@ dokku mongo:backup lolipop my-s3-bucket --use-iam dokku mongo:backup-set-encryption ``` -examples: - Set a gpg passphrase for backups: ```shell dokku mongo:backup-set-encryption lolipop ``` + ### unsets encryption for future backups of the mongo service ```shell @@ -587,13 +544,12 @@ dokku mongo:backup-set-encryption lolipop dokku mongo:backup-unset-encryption ``` -examples: - Unset a gpg encryption key for backups: ```shell dokku mongo:backup-unset-encryption lolipop ``` + ### schedules a backup of the mongo service ```shell @@ -601,8 +557,6 @@ dokku mongo:backup-unset-encryption lolipop dokku mongo:backup-schedule [--use-iam] ``` -examples: - Schedule a backup: > 'schedule' is a crontab expression, eg. "0 3 * * *" for each day at 3am @@ -616,6 +570,7 @@ Schedule a backup and authenticate via iam: ```shell dokku mongo:backup-schedule lolipop "0 3 * * *" my-s3-bucket --use-iam ``` + ### cat the contents of the configured backup cronfile for the service ```shell @@ -623,13 +578,12 @@ dokku mongo:backup-schedule lolipop "0 3 * * *" my-s3-bucket --use-iam dokku mongo:backup-schedule-cat ``` -examples: - Cat the contents of the configured backup cronfile for the service: ```shell dokku mongo:backup-schedule-cat lolipop ``` + ### unschedules the backup of the mongo service ```shell @@ -637,8 +591,6 @@ dokku mongo:backup-schedule-cat lolipop dokku mongo:backup-unschedule ``` -examples: - Remove the scheduled backup from cron: ```shell diff --git a/bin/generate b/bin/generate index 805ee7c..3ddf821 100755 --- a/bin/generate +++ b/bin/generate @@ -5,6 +5,17 @@ import os import re +def compile(service, version, alias, scheme, ports, unimplemented, dokku_version): + return "\n\n".join([ + header(service), + description(service, version), + requirements_section(dokku_version), + installation_section(service, dokku_version), + commands_section(service, alias, scheme, ports, unimplemented), + usage_section(service, alias, scheme, ports, unimplemented), + ]).replace("\n\n\n\n\n", "\n").replace("\n\n\n\n", "\n").replace("\n\n\n", "\n\n") + + def header(service): return " ".join([ f"# dokku {service}", @@ -17,7 +28,7 @@ def description(service, version): return f"Official {service} plugin for dokku. Currently defaults to installing [{service} {version}](https://hub.docker.com/_/{service}/)." -def requirements(dokku_version): +def requirements_section(dokku_version): return "\n".join([ "## Requirements", "", @@ -26,7 +37,7 @@ def requirements(dokku_version): ]) -def installation(service, dokku_version): +def installation_section(service, dokku_version): return "\n".join([ "## Installation", "", @@ -37,7 +48,7 @@ def installation(service, dokku_version): ]) -def commands(service, alias, scheme, ports): +def commands_section(service, alias, scheme, ports, unimplemented): content = [ "## Commands", "", @@ -50,6 +61,8 @@ def commands(service, alias, scheme, ports): command_list = [] descriptions = [] for filename in subcommands: + if filename in unimplemented: + continue data = command_data(filename, service, alias, scheme, ports) description = data["description"] arguments = data["arguments_string"] @@ -68,77 +81,65 @@ def commands(service, alias, scheme, ports): return "\n".join(content) -def usage(service, alias, scheme, ports): +def usage_section(service, alias, scheme, ports, unimplemented): return "\n\n".join([ "## Usage", f"Help for any commands can be displayed by specifying the command as an argument to {service}:help. Please consult the `{service}:help` command for any undocumented commands.", - usage_intro(service, alias, scheme, ports), - usage_lifecycle(service, alias, scheme, ports), - usage_automation(service, alias, scheme, ports), - usage_data_management(service, alias, scheme, ports), - usage_backup(service, alias, scheme, ports), - usage_docker_pull(service, alias, scheme, ports), + usage_intro(service, alias, scheme, ports, unimplemented), + usage_lifecycle(service, alias, scheme, ports, unimplemented), + usage_automation(service, alias, scheme, ports, unimplemented), + usage_data_management(service, alias, scheme, ports, unimplemented), + usage_backup(service, alias, scheme, ports, unimplemented), + usage_docker_pull(service, alias, scheme, ports, unimplemented), ]) -def usage_intro(service, alias, scheme, ports): - return "\n".join([ - "### Basic Usage", - command_help("list", service, alias, scheme, ports), - command_help("create", service, alias, scheme, ports), - command_help("info", service, alias, scheme, ports), - command_help("logs", service, alias, scheme, ports), - command_help("link", service, alias, scheme, ports), - command_help("unlink", service, alias, scheme, ports), - command_help("destroy", service, alias, scheme, ports), - ]) +def usage_intro(service, alias, scheme, ports, unimplemented): + commands = ["create", "info", "list", "logs", "link", "unlink"] + content = ["### Basic Usage"] + + return fetch_commands_content(service, alias, scheme, ports, unimplemented, commands, content) -def usage_lifecycle(service, alias, scheme, ports): - return "\n".join([ +def usage_lifecycle(service, alias, scheme, ports, unimplemented): + commands = ["connect", "enter", "expose", "unexpose", "promote", "start", "stop", "restart", "upgrade"] + content = [ "### Service Lifecycle", "", "The lifecycle of each service can be managed through the following commands:", "", - command_help("connect", service, alias, scheme, ports), - command_help("enter", service, alias, scheme, ports), - command_help("expose", service, alias, scheme, ports), - command_help("unexpose", service, alias, scheme, ports), - command_help("promote", service, alias, scheme, ports), - command_help("restart", service, alias, scheme, ports), - command_help("start", service, alias, scheme, ports), - command_help("stop", service, alias, scheme, ports), - command_help("upgrade", service, alias, scheme, ports), - ]) + ] + + return fetch_commands_content(service, alias, scheme, ports, unimplemented, commands, content) -def usage_automation(service, alias, scheme, ports): - return "\n".join([ +def usage_automation(service, alias, scheme, ports, unimplemented): + commands = ["app-links", "clone", "exists", "linked", "links"] + content = [ "### Service Automation", "", "Service scripting can be executed using the following commands:", "", - command_help("app-links", service, alias, scheme, ports), - command_help("clone", service, alias, scheme, ports), - command_help("exists", service, alias, scheme, ports), - command_help("linked", service, alias, scheme, ports), - command_help("links", service, alias, scheme, ports), - ]) + ] + + return fetch_commands_content(service, alias, scheme, ports, unimplemented, commands, content) -def usage_data_management(service, alias, scheme, ports): - return "\n".join([ +def usage_data_management(service, alias, scheme, ports, unimplemented): + commands = ["import", "export"] + content = [ "### Data Management", "", "The underlying service data can be imported and exported with the following commands:", "", - command_help("import", service, alias, scheme, ports), - command_help("export", service, alias, scheme, ports), - ]) + ] + + return fetch_commands_content(service, alias, scheme, ports, unimplemented, commands, content) -def usage_backup(service, alias, scheme, ports): - return "\n".join([ +def usage_backup(service, alias, scheme, ports, unimplemented): + commands = ["backup-auth", "backup-deauth", "backup", "backup-set-encryption", "backup-unset-encryption", "backup-schedule", "backup-schedule-cat", "backup-unschedule",] + content = [ "### Backups", "", "Datastore backups are supported via AWS S3 and S3 compatible services like [minio](https://github.com/minio/minio).", @@ -147,18 +148,12 @@ def usage_backup(service, alias, scheme, ports): "", "Backups can be performed using the backup commands:", "", - command_help("backup-auth", service, alias, scheme, ports), - command_help("backup-deauth", service, alias, scheme, ports), - command_help("backup", service, alias, scheme, ports), - command_help("backup-set-encryption", service, alias, scheme, ports), - command_help("backup-unset-encryption", service, alias, scheme, ports), - command_help("backup-schedule", service, alias, scheme, ports), - command_help("backup-schedule-cat", service, alias, scheme, ports), - command_help("backup-unschedule", service, alias, scheme, ports), - ]) + ] + + return fetch_commands_content(service, alias, scheme, ports, unimplemented, commands, content) -def usage_docker_pull(service, alias, scheme, ports): +def usage_docker_pull(service, alias, scheme, ports, unimplemented): service_prefix = service.upper() return "\n".join([ "### Disabling `docker pull` calls", @@ -169,6 +164,21 @@ def usage_docker_pull(service, alias, scheme, ports): ]) +def fetch_commands_content(service, alias, scheme, ports, unimplemented, commands, content): + i = 0 + for command in commands: + output = command_help(command, service, alias, scheme, ports, unimplemented) + if output == "": + continue + content.append(output) + i += 1 + + if i == 0: + return "" + + return "\n".join(content) + + def parse_args(line): line = line.strip() arguments = [] @@ -195,7 +205,10 @@ def parse_args(line): return " ".join(arguments) -def command_help(command, service, alias, scheme, ports): +def command_help(command, service, alias, scheme, ports, unimplemented): + if command in unimplemented: + return "" + data = command_data(command, service, alias, scheme, ports) content = [ f"### {data['description']}", @@ -221,12 +234,10 @@ def command_help(command, service, alias, scheme, ports): # content.append(f"- {flag}") if len(data["examples"]) > 0: - content.append("") - content.append("examples:") content.append("") content.append(data["examples"]) - return "\n".join(content) + return "\n" + "\n".join(content) def command_data(command, service, alias, scheme, ports): @@ -339,7 +350,7 @@ def command_data(command, service, alias, scheme, ports): def process_sentence(sentence_lines): sentence_lines = " ".join(sentence_lines) - sentences = ". ".join(i.strip().capitalize() for i in sentence_lines.split(".")) + sentences = ". ".join(i.strip().capitalize() for i in sentence_lines.split(".")).strip() if not sentences.endswith(".") and not sentences.endswith(":"): sentences += ":" return sentences @@ -359,21 +370,11 @@ def process_codeblock(codeblock_lines): return f"```\n{codeblock_lines}\n```" -def compile(service, version, alias, scheme, ports, dokku_version): - return "\n\n".join([ - header(service), - description(service, version), - requirements(dokku_version), - installation(service, dokku_version), - commands(service, alias, scheme, ports), - usage(service, alias, scheme, ports), - ]) - - def main(): service = None version = None alias = None + unimplemented = [] with open("config") as f: for line in f.readlines(): if "IMAGE_VERSION=${" in line: @@ -386,8 +387,12 @@ def main(): scheme = re.search('"(.+)"', line).group(1) if "PLUGIN_DATASTORE_PORTS=" in line: ports = re.search('\((.+)\)', line).group(1).split(" ") + if "PLUGIN_UNIMPLEMENTED_SUBCOMMANDS=" in line: + match = re.search('\((.+)\)', line) + if match is not None: + unimplemented = [s.strip('"') for s in match.group(1).split(" ")] - text = compile(service, version, alias, scheme, ports, "0.12.x+") + text = compile(service, version, alias, scheme, ports, unimplemented, "0.12.x+") base_path = os.path.dirname(os.path.dirname(os.path.realpath(__file__))) readme_file = os.path.join(base_path, 'README.md') diff --git a/subcommands/info b/subcommands/info index 21dfd4a..6aca3f1 100755 --- a/subcommands/info +++ b/subcommands/info @@ -30,7 +30,7 @@ service-info-cmd() { #F --service-root, show the service root directory #F --status, show the service running status #F --version, show the service image version - declare desc="print the connection information" + declare desc="print the service information" local cmd="$PLUGIN_COMMAND_PREFIX:info" argv=("$@") [[ ${argv[0]} == "$cmd" ]] && shift 1 declare SERVICE="$1" INFO_FLAG="$2"