From ad40041a238a13add62888fc92f4ff4f0f10dcfb Mon Sep 17 00:00:00 2001 From: Jose Diaz-Gonzalez Date: Mon, 13 Sep 2021 01:21:18 -0400 Subject: [PATCH] docs: add ability to inject supplementary documentation into the readme Some commands - such as link or upgrade - have extra documenation on a per-plugin basis. Rather than make some sort of weird templating logic in the help output generation, that documentation is added directly to the repository and then injected at generation time. --- README.md | 2 +- bin/generate | 8 +++++++- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index c90ea32..a464b0e 100644 --- a/README.md +++ b/README.md @@ -53,7 +53,7 @@ mongo:upgrade [--upgrade-flags...] # upgrade service t ## Usage -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. +Help for any commands can be displayed by specifying the command as an argument to mongo:help. Plugin help output in conjunction with any files in the `docs/` folder is used to generate the plugin documentation. Please consult the `mongo:help` command for any undocumented commands. ### Basic Usage diff --git a/bin/generate b/bin/generate index 82bdfc5..2e19392 100755 --- a/bin/generate +++ b/bin/generate @@ -119,7 +119,7 @@ def usage_section(service, variable, alias, image, scheme, ports, options, unimp 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.", + 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), @@ -308,6 +308,12 @@ def command_help(command, service, variable, alias, image, scheme, ports, option content.append("") content.append(data["examples"]) + doc_file = os.path.join("docs", f"{command}.md") + if os.path.isfile(doc_file): + content.append("") + with open(doc_file) as f: + content.append(f.read()) + return "\n" + "\n".join(content)