Skip to content

Commit

Permalink
docs: update docs and generation script
Browse files Browse the repository at this point in the history
  • Loading branch information
@josegonzalez
josegonzalez committed Dec 10, 2023
1 parent 903c447 commit 92ec118
Show file tree
Hide file tree
Showing 2 changed files with 181 additions and 46 deletions.
3 changes: 1 addition & 2 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,7 @@ Create a typesense service named lollipop:
dokku typesense:create lollipop
```

You can also specify the image and image version to use for the service. It _must_ be compatible with the typesense/typesense image.
You can also specify the image and image version to use for the service. It *must* be compatible with the typesense/typesense image.

```shell
export TYPESENSE_IMAGE="typesense/typesense"
Expand Down Expand Up @@ -525,7 +525,6 @@ List all apps linked to the `lollipop` typesense service.
```shell
dokku typesense:links lollipop
```

### Backups

Datastore backups are supported via AWS S3 and S3 compatible services like [minio](https://github.com/minio/minio).
Expand Down
224 changes: 180 additions & 44 deletions bin/generate
View file
Original file line number Diff line number Diff line change
@@ -1,15 +1,30 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
from __future__ import print_function

import os
import re


def compile(service, version, variable, alias, image, scheme, ports, sponsors, options, unimplemented, dokku_version):
prefix = "\n\n".join([
header(service),
description(service, image, version),
])
def compile(
service,
version,
variable,
alias,
image,
scheme,
ports,
sponsors,
options,
unimplemented,
dokku_version,
):
prefix = "\n\n".join(
[
header(service),
description(service, image, version),
]
)

if len(sponsors) > 0:
prefix += "\n\n"
Expand All @@ -21,8 +36,19 @@ def compile(service, version, variable, alias, image, scheme, ports, sponsors, o
prefix,
requirements_section(dokku_version),
installation_section(service, dokku_version),
commands_section(service, variable, alias, image, scheme, ports, unimplemented),
usage_section(service, variable, alias, image, scheme, ports, options, unimplemented),
commands_section(
service, variable, alias, image, scheme, ports, unimplemented
),
usage_section(
service,
variable,
alias,
image,
scheme,
ports,
options,
unimplemented,
),
]
)
.replace("\n\n\n\n\n", "\n")
Expand Down Expand Up @@ -55,17 +81,25 @@ def sponsors_section(service, sponsors):
if len(sponsors) == 0:
return ""

sponsor_data = ["## Sponsors", "", f"The {service} plugin was generously sponsored by the following:", ""]
sponsor_data = [
"## Sponsors",
"",
f"The {service} plugin was generously sponsored by the following:",
"",
]
sponsor_data.extend([f"- [{s}](https://github.com/{s})" for s in sponsors])

return "\n".join(
sponsor_data
)
return "\n".join(sponsor_data)


def requirements_section(dokku_version):
return "\n".join(
["## Requirements", "", f"- dokku {dokku_version}", "- docker 1.8.x",]
[
"## Requirements",
"",
f"- dokku {dokku_version}",
"- docker 1.8.x",
]
)


Expand Down Expand Up @@ -115,17 +149,31 @@ def commands_section(service, variable, alias, image, scheme, ports, unimplement
return "\n".join(content)


def usage_section(service, variable, alias, image, scheme, ports, options, unimplemented):
def usage_section(
service, variable, alias, image, scheme, ports, options, unimplemented
):
return "\n\n".join(
[
"## Usage",
f"Help for any commands can be displayed by specifying the command as an argument to {service}:help. Plugin help output in conjunction with any files in the `docs/` folder is used to generate the plugin documentation. Please consult the `{service}:help` command for any undocumented commands.",
usage_intro(service, variable, alias, image, scheme, ports, options, unimplemented),
usage_lifecycle(service, variable, alias, image, scheme, ports, options, unimplemented),
usage_automation(service, variable, alias, image, scheme, ports, options, unimplemented),
usage_data_management(service, variable, alias, image, scheme, ports, options, unimplemented),
usage_backup(service, variable, alias, image, scheme, ports, options, unimplemented),
usage_docker_pull(service, variable, alias, image, scheme, ports, options, unimplemented),
usage_intro(
service, variable, alias, image, scheme, ports, options, unimplemented
),
usage_lifecycle(
service, variable, alias, image, scheme, ports, options, unimplemented
),
usage_automation(
service, variable, alias, image, scheme, ports, options, unimplemented
),
usage_data_management(
service, variable, alias, image, scheme, ports, options, unimplemented
),
usage_backup(
service, variable, alias, image, scheme, ports, options, unimplemented
),
usage_docker_pull(
service, variable, alias, image, scheme, ports, options, unimplemented
),
]
)

Expand All @@ -135,11 +183,22 @@ def usage_intro(service, variable, alias, image, scheme, ports, options, unimple
content = ["### Basic Usage"]

return fetch_commands_content(
service, variable, alias, image, scheme, ports, options, unimplemented, commands, content
service,
variable,
alias,
image,
scheme,
ports,
options,
unimplemented,
commands,
content,
)


def usage_lifecycle(service, variable, alias, image, scheme, ports, options, unimplemented):
def usage_lifecycle(
service, variable, alias, image, scheme, ports, options, unimplemented
):
commands = [
"connect",
"enter",
Expand All @@ -160,11 +219,22 @@ def usage_lifecycle(service, variable, alias, image, scheme, ports, options, uni
]

return fetch_commands_content(
service, variable, alias, image, scheme, ports, options, unimplemented, commands, content
service,
variable,
alias,
image,
scheme,
ports,
options,
unimplemented,
commands,
content,
)


def usage_automation(service, variable, alias, image, scheme, ports, options, unimplemented):
def usage_automation(
service, variable, alias, image, scheme, ports, options, unimplemented
):
commands = ["app-links", "clone", "exists", "linked", "links"]
content = [
"### Service Automation",
Expand All @@ -174,11 +244,22 @@ def usage_automation(service, variable, alias, image, scheme, ports, options, un
]

return fetch_commands_content(
service, variable, alias, image, scheme, ports, options, unimplemented, commands, content
service,
variable,
alias,
image,
scheme,
ports,
options,
unimplemented,
commands,
content,
)


def usage_data_management(service, variable, alias, image, scheme, ports, options, unimplemented):
def usage_data_management(
service, variable, alias, image, scheme, ports, options, unimplemented
):
commands = ["import", "export"]
content = [
"### Data Management",
Expand All @@ -188,11 +269,22 @@ def usage_data_management(service, variable, alias, image, scheme, ports, option
]

return fetch_commands_content(
service, variable, alias, image, scheme, ports, options, unimplemented, commands, content
service,
variable,
alias,
image,
scheme,
ports,
options,
unimplemented,
commands,
content,
)


def usage_backup(service, variable, alias, image, scheme, ports, options, unimplemented):
def usage_backup(
service, variable, alias, image, scheme, ports, options, unimplemented
):
commands = [
"backup-auth",
"backup-deauth",
Expand All @@ -215,11 +307,22 @@ def usage_backup(service, variable, alias, image, scheme, ports, options, unimpl
]

return fetch_commands_content(
service, variable, alias, image, scheme, ports, options, unimplemented, commands, content
service,
variable,
alias,
image,
scheme,
ports,
options,
unimplemented,
commands,
content,
)


def usage_docker_pull(service, variable, alias, image, scheme, ports, options, unimplemented):
def usage_docker_pull(
service, variable, alias, image, scheme, ports, options, unimplemented
):
service_prefix = service.upper()
return "\n".join(
[
Expand All @@ -233,11 +336,30 @@ def usage_docker_pull(service, variable, alias, image, scheme, ports, options, u


def fetch_commands_content(
service, variable, alias, image, scheme, ports, options, unimplemented, commands, content
service,
variable,
alias,
image,
scheme,
ports,
options,
unimplemented,
commands,
content,
):
i = 0
for command in commands:
output = command_help(command, service, variable, alias, image, scheme, ports, options, unimplemented)
output = command_help(
command,
service,
variable,
alias,
image,
scheme,
ports,
options,
unimplemented,
)
if output == "":
continue
content.append(output)
Expand Down Expand Up @@ -275,7 +397,9 @@ def parse_args(line):
return " ".join(arguments)


def command_help(command, service, variable, alias, image, scheme, ports, options, unimplemented):
def command_help(
command, service, variable, alias, image, scheme, ports, options, unimplemented
):
if command in unimplemented:
return ""

Expand All @@ -285,7 +409,7 @@ def command_help(command, service, variable, alias, image, scheme, ports, option
"",
"```shell",
"# usage",
f"dokku {service}:{command} {data['arguments_string']}",
f"dokku {service}:{command} {data['arguments_string']}".strip(),
"```",
]

Expand Down Expand Up @@ -442,11 +566,11 @@ def process_sentence(sentence_lines):
parts = []
for word in sentence.strip().split(" "):
if word.isupper() and len(word) > 1:
for ending in [':', '.']:
for ending in [":", "."]:
if word.endswith(ending):
word = '`{0}`{1}'.format(word[:-1], ending)
word = "`{0}`{1}".format(word[:-1], ending)
else:
word = '`{0}`'.format(word)
word = "`{0}`".format(word)
parts.append(word)
text.append(" ".join(parts))

Expand Down Expand Up @@ -491,10 +615,10 @@ def main():

with open("Dockerfile") as f:
for line in f.readlines():
if "FROM " in line:
image, version = line.split(" ")[1].split(":")
image = image.strip()
version = version.strip()
if "FROM " in line:
image, version = line.split(" ")[1].split(":")
image = image.strip()
version = version.strip()

with open("config") as f:
for line in f.readlines():
Expand Down Expand Up @@ -524,10 +648,22 @@ def main():
with open("plugin.toml") as f:
for line in f.readlines():
if line.startswith("sponsors"):
sponsors = re.search("\[([\"\w\s,_-]+)\]", line).group(1)
sponsors = [s.strip("\"") for s in sponsors.split(",")]

text = compile(service, version, variable, alias, image, scheme, ports, sponsors, options, unimplemented, "0.19.x+")
sponsors = re.search('\[(["\w\s,_-]+)\]', line).group(1)
sponsors = [s.strip('"') for s in sponsors.split(",")]

text = compile(
service,
version,
variable,
alias,
image,
scheme,
ports,
sponsors,
options,
unimplemented,
"0.19.x+",
)

base_path = os.path.dirname(os.path.dirname(os.path.realpath(__file__)))
readme_file = os.path.join(base_path, "README.md")
Expand Down

0 comments on commit 92ec118

Please sign in to comment.