diff --git a/README.md b/README.md index b4cc2a5..2d531d2 100644 --- a/README.md +++ b/README.md @@ -77,15 +77,15 @@ Create a mysql service named lolipop: dokku mysql: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 mysql image. ```shell -export DATABASE_IMAGE="${PLUGIN_IMAGE}" +export DATABASE_IMAGE="mysql" export DATABASE_IMAGE_VERSION="${PLUGIN_IMAGE_VERSION}" dokku mysql:create lolipop ``` -You can also specify custom environment variables to start the mysql service in semi-colon separated form. +You can also specify custom environment variables to start the mysql service in semi-colon separated form. ```shell export DATABASE_CUSTOM_ENV="USER=alpha;HOST=beta" @@ -181,7 +181,7 @@ flags: - `-a|--alias "BLUE_DATABASE"`: an alternative alias to use for linking to an app via environment variable - `-q|--querystring "pool=5"`: ampersand delimited querystring arguments to append to the service link -A mysql 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 mysql 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 @@ -212,14 +212,14 @@ The host exposed here only works internally in docker containers. If you want yo dokku mysql:link other_service playground ``` -It is possible to change the protocol for database_url by setting the environment variable database_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 `DATABASE_URL` by setting the environment variable `MYSQL_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 DATABASE_DATABASE_SCHEME=mysql2 +dokku config:set playground MYSQL_DATABASE_SCHEME=mysql2 dokku mysql:link lolipop playground ``` -This will cause database_url to be set as: +This will cause `DATABASE_URL` to be set as: ``` mysql2://lolipop:SOME_PASSWORD@dokku-mysql-lolipop:3306/lolipop @@ -264,13 +264,13 @@ dokku mysql:connect lolipop dokku mysql:enter ``` -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 mysql: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 mysql:enter lolipop touch /tmp/test @@ -283,10 +283,10 @@ dokku mysql:enter lolipop touch /tmp/test dokku mysql:expose ``` -Expose the service on the service's normal ports, allowing access to it from the public interface (0. 0. 0. 0): +Expose the service on the service's normal ports, allowing access to it from the public interface (`0.0.0.0`): ```shell -dokku mysql:expose lolipop ${PLUGIN_DATASTORE_PORTS[@]} +dokku mysql:expose lolipop 3306 ``` ### unexpose a previously exposed mysql service @@ -296,7 +296,7 @@ dokku mysql:expose lolipop ${PLUGIN_DATASTORE_PORTS[@]} dokku mysql:unexpose ``` -Unexpose the service, removing access to it from the public interface (0. 0. 0. 0): +Unexpose the service, removing access to it from the public interface (`0.0.0.0`): ```shell dokku mysql:unexpose lolipop @@ -323,7 +323,7 @@ You can promote the new service to be the primary one: dokku mysql:promote other_service playground ``` -This will replace database_url with the url from other_service and generate another environment variable to hold the previous value if necessary. You could end up with the following for example: +This will replace `DATABASE_URL` with the url from other_service and generate another environment variable to hold the previous value if necessary. You could end up with the following for example: ``` DATABASE_URL=mysql://other_service:ANOTHER_PASSWORD@dokku-mysql-other-service:3306/other_service @@ -401,7 +401,7 @@ Service scripting can be executed using the following commands: dokku mysql:app-links ``` -List all mysql services that are linked to the 'playground' app. +List all mysql services that are linked to the 'playground' app. ```shell dokku mysql:app-links playground @@ -435,7 +435,7 @@ dokku mysql:clone lolipop lolipop-2 dokku mysql:exists ``` -Here we check if the lolipop mysql service exists. +Here we check if the lolipop mysql service exists. ```shell dokku mysql:exists lolipop @@ -448,7 +448,7 @@ dokku mysql:exists lolipop dokku mysql:linked ``` -Here we check if the lolipop mysql service is linked to the 'playground' app. +Here we check if the lolipop mysql service is linked to the 'playground' app. ```shell dokku mysql:linked lolipop playground @@ -461,7 +461,7 @@ dokku mysql:linked lolipop playground dokku mysql:links ``` -List all apps linked to the 'lolipop' mysql service. +List all apps linked to the 'lolipop' mysql service. ```shell dokku mysql:links lolipop @@ -566,7 +566,7 @@ flags: - `-u|--use-iam`: use the IAM profile associated with the current server -Backup the 'lolipop' service to the 'my-s3-bucket' bucket on aws: +Backup the 'lolipop' service to the 'my-s3-bucket' bucket on ``AWS`:` ```shell dokku mysql:backup lolipop my-s3-bucket --use-iam @@ -579,7 +579,7 @@ dokku mysql:backup lolipop my-s3-bucket --use-iam dokku mysql:backup-set-encryption ``` -Set the gpg-compatible passphrase for encrypting backups for backups: +Set the GPG-compatible passphrase for encrypting backups for backups: ```shell dokku mysql:backup-set-encryption lolipop @@ -592,7 +592,7 @@ dokku mysql:backup-set-encryption lolipop dokku mysql:backup-unset-encryption ``` -Unset the gpg encryption passphrase for backups: +Unset the `GPG` encryption passphrase for backups: ```shell dokku mysql:backup-unset-encryption lolipop diff --git a/bin/generate b/bin/generate index d62f792..0172771 100755 --- a/bin/generate +++ b/bin/generate @@ -5,7 +5,7 @@ import os import re -def compile(service, version, alias, scheme, ports, unimplemented, dokku_version): +def compile(service, version, variable, alias, image, scheme, ports, unimplemented, dokku_version): return ( "\n\n".join( [ @@ -13,8 +13,8 @@ def compile(service, version, alias, scheme, ports, unimplemented, dokku_version 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), + commands_section(service, variable, alias, image, scheme, ports, unimplemented), + usage_section(service, variable, alias, image, scheme, ports, unimplemented), ] ) .replace("\n\n\n\n\n", "\n") @@ -56,7 +56,7 @@ def installation_section(service, dokku_version): ) -def commands_section(service, alias, scheme, ports, unimplemented): +def commands_section(service, variable, alias, image, scheme, ports, unimplemented): content = [ "## Commands", "", @@ -71,7 +71,7 @@ def commands_section(service, alias, scheme, ports, unimplemented): for filename in subcommands: if filename in unimplemented: continue - data = command_data(filename, service, alias, scheme, ports) + data = command_data(filename, service, variable, alias, image, scheme, ports) description = data["description"] arguments = data["arguments_string"] @@ -89,31 +89,31 @@ def commands_section(service, alias, scheme, ports, unimplemented): return "\n".join(content) -def usage_section(service, alias, scheme, ports, unimplemented): +def usage_section(service, variable, alias, image, 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, 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), + usage_intro(service, variable, alias, image, scheme, ports, unimplemented), + usage_lifecycle(service, variable, alias, image, scheme, ports, unimplemented), + usage_automation(service, variable, alias, image, scheme, ports, unimplemented), + usage_data_management(service, variable, alias, image, scheme, ports, unimplemented), + usage_backup(service, variable, alias, image, scheme, ports, unimplemented), + usage_docker_pull(service, variable, alias, image, scheme, ports, unimplemented), ] ) -def usage_intro(service, alias, scheme, ports, unimplemented): +def usage_intro(service, variable, alias, image, scheme, ports, unimplemented): commands = ["create", "info", "list", "logs", "link", "unlink"] content = ["### Basic Usage"] return fetch_commands_content( - service, alias, scheme, ports, unimplemented, commands, content + service, variable, alias, image, scheme, ports, unimplemented, commands, content ) -def usage_lifecycle(service, alias, scheme, ports, unimplemented): +def usage_lifecycle(service, variable, alias, image, scheme, ports, unimplemented): commands = [ "connect", "enter", @@ -133,11 +133,11 @@ def usage_lifecycle(service, alias, scheme, ports, unimplemented): ] return fetch_commands_content( - service, alias, scheme, ports, unimplemented, commands, content + service, variable, alias, image, scheme, ports, unimplemented, commands, content ) -def usage_automation(service, alias, scheme, ports, unimplemented): +def usage_automation(service, variable, alias, image, scheme, ports, unimplemented): commands = ["app-links", "clone", "exists", "linked", "links"] content = [ "### Service Automation", @@ -147,11 +147,11 @@ def usage_automation(service, alias, scheme, ports, unimplemented): ] return fetch_commands_content( - service, alias, scheme, ports, unimplemented, commands, content + service, variable, alias, image, scheme, ports, unimplemented, commands, content ) -def usage_data_management(service, alias, scheme, ports, unimplemented): +def usage_data_management(service, variable, alias, image, scheme, ports, unimplemented): commands = ["import", "export"] content = [ "### Data Management", @@ -161,11 +161,11 @@ def usage_data_management(service, alias, scheme, ports, unimplemented): ] return fetch_commands_content( - service, alias, scheme, ports, unimplemented, commands, content + service, variable, alias, image, scheme, ports, unimplemented, commands, content ) -def usage_backup(service, alias, scheme, ports, unimplemented): +def usage_backup(service, variable, alias, image, scheme, ports, unimplemented): commands = [ "backup-auth", "backup-deauth", @@ -188,11 +188,11 @@ def usage_backup(service, alias, scheme, ports, unimplemented): ] return fetch_commands_content( - service, alias, scheme, ports, unimplemented, commands, content + service, variable, alias, image, scheme, ports, unimplemented, commands, content ) -def usage_docker_pull(service, alias, scheme, ports, unimplemented): +def usage_docker_pull(service, variable, alias, image, scheme, ports, unimplemented): service_prefix = service.upper() return "\n".join( [ @@ -206,11 +206,11 @@ def usage_docker_pull(service, alias, scheme, ports, unimplemented): def fetch_commands_content( - service, alias, scheme, ports, unimplemented, commands, content + service, variable, alias, image, scheme, ports, unimplemented, commands, content ): i = 0 for command in commands: - output = command_help(command, service, alias, scheme, ports, unimplemented) + output = command_help(command, service, variable, alias, image, scheme, ports, unimplemented) if output == "": continue content.append(output) @@ -248,11 +248,11 @@ def parse_args(line): return " ".join(arguments) -def command_help(command, service, alias, scheme, ports, unimplemented): +def command_help(command, service, variable, alias, image, scheme, ports, unimplemented): if command in unimplemented: return "" - data = command_data(command, service, alias, scheme, ports) + data = command_data(command, service, variable, alias, image, scheme, ports) content = [ f"### {data['description']}", "", @@ -283,7 +283,7 @@ def command_help(command, service, alias, scheme, ports, unimplemented): return "\n" + "\n".join(content) -def command_data(command, service, alias, scheme, ports): +def command_data(command, service, variable, alias, image, scheme, ports): description = None arguments = [] arguments_string = "" @@ -295,9 +295,12 @@ def command_data(command, service, alias, scheme, ports): line = line.replace("$PLUGIN_SERVICE", service) line = line.replace("$PLUGIN_COMMAND_PREFIX", service) line = line.replace("${PLUGIN_COMMAND_PREFIX}", service) + line = line.replace("${PLUGIN_VARIABLE}", variable) line = line.replace("${PLUGIN_DEFAULT_ALIAS}", alias) + line = line.replace("${PLUGIN_IMAGE}", image) line = line.replace("${PLUGIN_SCHEME}", scheme) line = line.replace("${PLUGIN_DATASTORE_PORTS[0]}", ports[0]) + line = line.replace("${PLUGIN_DATASTORE_PORTS[@]}", " ".join(ports)) if "declare desc" in line: description = re.search('"(.+)"', line).group(1) @@ -394,11 +397,34 @@ 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(".") + upperfirst(i.strip()) for i in sentence_lines.split(".") ).strip() if not sentences.endswith(".") and not sentences.endswith(":"): sentences += ":" - return sentences + + text = [] + for sentence in sentences.split("."): + parts = [] + for word in sentence.strip().split(" "): + if word.isupper() and len(word) > 1: + for ending in [':', '.']: + if word.endswith(ending): + word = '`{0}`{1}'.format(word[:-1], ending) + else: + word = '`{0}`'.format(word) + parts.append(word) + text.append(" ".join(parts)) + + text = ". ".join(text) + + # some cleanup + text = text.replace("(0. 0. 0. 0)", "(`0.0.0.0`)") + + return text + + +def upperfirst(x): + return x[:1].upper() + x[1:] def process_blockquote(blockquote_lines): @@ -418,16 +444,22 @@ def process_codeblock(codeblock_lines): def main(): service = None version = None + variable = None + image = None alias = None unimplemented = [] with open("config") as f: for line in f.readlines(): if "IMAGE_VERSION=${" in line: version = re.search('"(.+)"', line).group(1) + if "_IMAGE=${" in line: + image = re.search('"(.+)"', line).group(1) if "PLUGIN_COMMAND_PREFIX=" in line: service = re.search('"(.+)"', line).group(1) if "PLUGIN_DEFAULT_ALIAS=" in line: alias = re.search('"(.+)"', line).group(1) + if "PLUGIN_VARIABLE=" in line: + variable = re.search('"(.+)"', line).group(1) if "PLUGIN_SCHEME=" in line: scheme = re.search('"(.+)"', line).group(1) if "PLUGIN_DATASTORE_PORTS=" in line: @@ -437,7 +469,7 @@ def main(): if match is not None: unimplemented = [s.strip('"') for s in match.group(1).split(" ")] - text = compile(service, version, alias, scheme, ports, unimplemented, "0.12.x+") + text = compile(service, version, variable, alias, image, 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/link b/subcommands/link index 851229e..9a435d6 100755 --- a/subcommands/link +++ b/subcommands/link @@ -30,10 +30,10 @@ service-link-cmd() { #E use the 'expose' subcommand. another service can be linked to your app: #E dokku $PLUGIN_COMMAND_PREFIX:link other_service playground #E it is possible to change the protocol for ${PLUGIN_DEFAULT_ALIAS}_URL by setting the - #E environment variable ${PLUGIN_DEFAULT_ALIAS}_DATABASE_SCHEME on the app. doing so will + #E environment variable ${PLUGIN_VARIABLE}_DATABASE_SCHEME on the app. doing so will #E after linking will cause the plugin to think the service is not #E linked, and we advise you to unlink before proceeding. - #E dokku config:set playground ${PLUGIN_DEFAULT_ALIAS}_DATABASE_SCHEME=${PLUGIN_SCHEME}2 + #E dokku config:set playground ${PLUGIN_VARIABLE}_DATABASE_SCHEME=${PLUGIN_SCHEME}2 #E dokku $PLUGIN_COMMAND_PREFIX:link lolipop playground #E this will cause ${PLUGIN_DEFAULT_ALIAS}_URL to be set as: #E