Skip to content

Commit e6d5f55

Browse files
authored
Merge pull request #1735 from polywrap/pileks/feat/docs-manifest
Docs manifest 0.1.0
2 parents 55e8a7d + d4f93a7 commit e6d5f55

61 files changed

Lines changed: 1062 additions & 76 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

packages/cli/lang/en.json

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@
1414
"commands_build_keypressListener_exit": "Exit: [CTRL + C], [ESC], or [Q]",
1515
"commands_build_keypressListener_watching": "Watching",
1616
"commands_build_options_h": "Show usage information",
17-
"commands_build_options_m": "Path to the Polywrap Build manifest file (default: {default})",
17+
"commands_build_options_m": "Path to the Polywrap manifest file (default: {default})",
1818
"commands_build_options_o": "Output directory for build results (default: {default})",
1919
"commands_build_options_o_path": "path",
2020
"commands_build_options_options": "options",
@@ -194,6 +194,13 @@
194194
"commands_manifest_formatError": "Unsupported manifest format. Please make sure that you have the 'format' field present in {fileName} with one of the following values: {values}",
195195
"commands_manifest_migrate_targetFormatError": "Unsupported target format. Supported formats: {formats}",
196196
"commands_manifest_projectTypeError": "Unsupported project type.",
197+
"commands_docs_description": "Documentation commands",
198+
"commands_docs_init_description": "Initialize wrap docs",
199+
"commands_docs_init_m_path": "path",
200+
"commands_docs_options_m": "Path to the Polywrap manifest file (default: {default})",
201+
"commands_docs_init_error_manifest_exists": "The {manifestFile} manifest already exists.",
202+
"commands_docs_init_warn_update_manifest": "Set the 'extensions.docs' property to {docsManifestFile} within your project's root manifest at {manifestFile}",
203+
"commands_docs_init_msg_manifest_created": "Written docs manifest to {manifestFile}",
197204
"lib_codeGenerator_genCodeError": "Failed to generate types",
198205
"lib_codeGenerator_genCodeText": "Generate types",
199206
"lib_codeGenerator_genCodeWarning": "Warnings while generating types",

packages/cli/lang/es.json

Lines changed: 12 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@
1414
"commands_build_keypressListener_exit": "Exit: [CTRL + C], [ESC], or [Q]",
1515
"commands_build_keypressListener_watching": "Watching",
1616
"commands_build_options_h": "Show usage information",
17-
"commands_build_options_m": "Path to the Polywrap Build manifest file (default: {default})",
17+
"commands_build_options_m": "Path to the Polywrap manifest file (default: {default})",
1818
"commands_build_options_o": "Output directory for build results (default: {default})",
1919
"commands_build_options_o_path": "path",
2020
"commands_build_options_options": "options",
@@ -116,11 +116,11 @@
116116
"commands_create_error_badUrl": "URL {url} uses an invalid format. Valid URL formats: {formats}",
117117
"commands_create_options_command": "command",
118118
"commands_create_options_commands": "Commands",
119-
"commands_create_options_createApp": "Create a Polywrap application",
120-
"commands_create_options_createPlugin": "Create a Polywrap plugin",
121-
"commands_create_options_createProject": "Create a Polywrap wasm wrapper",
119+
"commands_create_options_createApp": "Create a Polywrap application.",
120+
"commands_create_options_createPlugin": "Create a Polywrap plugin.",
121+
"commands_create_options_createProject": "Create a Polywrap wasm wrapper.",
122122
"commands_create_options_h": "Show usage information",
123-
"commands_create_options_t": "Download template from a .git URL",
123+
"commands_create_options_t": "Download template from a URL.",
124124
"commands_create_options_t_url": "URL",
125125
"commands_create_options_formats": "formats",
126126
"commands_create_options_lang": "lang",
@@ -194,6 +194,13 @@
194194
"commands_manifest_formatError": "Unsupported manifest format. Please make sure that you have the 'format' field present in {fileName} with one of the following values: {values}",
195195
"commands_manifest_migrate_targetFormatError": "Unsupported target format. Supported formats: {formats}",
196196
"commands_manifest_projectTypeError": "Unsupported project type.",
197+
"commands_docs_description": "Documentation commands",
198+
"commands_docs_init_description": "Initialize wrap docs",
199+
"commands_docs_init_m_path": "path",
200+
"commands_docs_options_m": "Path to the Polywrap manifest file (default: {default})",
201+
"commands_docs_init_error_manifest_exists": "The {manifestFile} manifest already exists.",
202+
"commands_docs_init_warn_update_manifest": "Set the 'extensions.docs' property to {docsManifestFile} within your project's root manifest at {manifestFile}",
203+
"commands_docs_init_msg_manifest_created": "Written docs manifest to {manifestFile}",
197204
"lib_codeGenerator_genCodeError": "Failed to generate types",
198205
"lib_codeGenerator_genCodeText": "Generate types",
199206
"lib_codeGenerator_genCodeWarning": "Warnings while generating types",
Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
import { polywrapCli } from "../utils";
2+
import { defaultDocsManifest, intlMsg } from "../../../";
3+
4+
import { Commands, runCli } from "@polywrap/cli-js";
5+
import { GetPathToCliTestFiles } from "@polywrap/test-cases";
6+
import fse from "fs-extra";
7+
import path from "path";
8+
9+
const DOCS_HELP = `Usage: polywrap docs [options] [command]
10+
11+
Documentation commands
12+
13+
Options:
14+
-h, --help display help for command
15+
16+
Commands:
17+
init|i [options] Initialize wrap docs
18+
help [command] display help for command
19+
`;
20+
21+
const DOCS_INIT_HELP = `Usage: polywrap docs init|i [options]
22+
23+
Initialize wrap docs
24+
25+
Options:
26+
-m, --manifest-file <path> Path to the Polywrap manifest file (default:
27+
polywrap.yaml | polywrap.yml)
28+
-v, --verbose Verbose output (default: false)
29+
-q, --quiet Suppress output (default: false)
30+
-l, --log-file [path] Log file to save console output to
31+
-h, --help display help for command
32+
`;
33+
34+
describe("docs command", () => {
35+
const testCaseRoot = path.join(GetPathToCliTestFiles(), "build-cmd/wasm/assemblyscript/001-sanity");
36+
const manifestFileName = defaultDocsManifest[0];
37+
const manifestFile = path.join(testCaseRoot, manifestFileName);
38+
39+
it("should show help text", async () => {
40+
const { exitCode, stdout, stderr } = await runCli({
41+
args: ["docs"],
42+
config: {
43+
cli: polywrapCli
44+
}
45+
});
46+
47+
expect(stderr).toBe(DOCS_HELP);
48+
expect(stdout).toBe("");
49+
expect(exitCode).toEqual(1);
50+
});
51+
52+
describe("init command", () => {
53+
it("should show help text", async () => {
54+
const { exitCode, stdout, stderr } = await Commands.docs.init({
55+
help: true
56+
}, {
57+
cli: polywrapCli,
58+
cwd: testCaseRoot
59+
});
60+
61+
expect(stdout).toBe(DOCS_INIT_HELP);
62+
expect(stderr).toBe("");
63+
expect(exitCode).toEqual(0);
64+
});
65+
66+
it("should set up wrap docs - no file collisions", async () => {
67+
const { exitCode, stdout, stderr } = await Commands.docs.init({}, {
68+
cli: polywrapCli,
69+
cwd: testCaseRoot
70+
});
71+
72+
expect(stdout).toContain(intlMsg.commands_docs_init_msg_manifest_created({
73+
manifestFile: manifestFileName
74+
}));
75+
expect(stderr).toContain("Set the 'extensions.docs' property");
76+
expect(exitCode).toEqual(0);
77+
expect(fse.existsSync(manifestFile)).toBe(true);
78+
79+
fse.rmSync(manifestFile);
80+
});
81+
82+
it("should error when setting up wrap docs - manifest file collision", async () => {
83+
await fse.createFile(manifestFile);
84+
85+
const { exitCode, stdout, stderr } = await Commands.docs.init({}, {
86+
cli: polywrapCli,
87+
cwd: testCaseRoot
88+
});
89+
90+
expect(stderr).toContain(
91+
intlMsg.commands_docs_init_error_manifest_exists({
92+
manifestFile: manifestFileName,
93+
})
94+
);
95+
expect(stdout).toBe("");
96+
expect(exitCode).toEqual(1);
97+
98+
fse.rmSync(manifestFile);
99+
});
100+
});
101+
});

packages/cli/src/__tests__/e2e/p1/help.spec.ts

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ Commands:
1717
infra|i [options] <action> Modular Infrastructure-As-Code Orchestrator
1818
manifest|m Inspect & Migrade Polywrap Manifests
1919
test|t [options] Execute Tests
20+
docs Documentation commands
2021
help [command] display help for command
2122
`;
2223

packages/cli/src/__tests__/e2e/p1/infra.spec.ts

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,8 @@ const waitForPorts = (ports: { port: number; expected: boolean }[]) => {
8888
});
8989
};
9090

91+
jest.setTimeout(150000);
92+
9193
describe("e2e tests for infra command", () => {
9294
beforeAll(() => {
9395
process.env = {

packages/cli/src/__tests__/e2e/p1/manifest.spec.ts

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ Migrates the polywrap project manifest to the latest version.
3030
Arguments:
3131
type Type of manifest file to migrate (default:
3232
project) (choices: "project", "build", "deploy",
33-
"infra", "workflow", default: "project")
33+
"infra", "workflow", "docs", default: "project")
3434
3535
Options:
3636
-m, --manifest-file <path> Path to the manifest file (default: polywrap.yaml
@@ -48,8 +48,8 @@ Prints out the schema for the current manifest format.
4848
4949
Arguments:
5050
type Type of manifest file to migrate (default:
51-
project) (choices: \"project\", \"build\", \"deploy\",
52-
\"infra\", \"workflow\", default: \"project\")
51+
project) (choices: "project", "build", "deploy",
52+
"infra", "workflow", "docs", default: "project")
5353
5454
Options:
5555
-r, --raw Output raw JSON Schema
@@ -138,7 +138,7 @@ describe("e2e tests for manifest command", () => {
138138
});
139139

140140
expect(error).toBe(
141-
`error: command-argument value 'invalid-arg' is invalid for argument 'type'. Allowed choices are project, build, deploy, infra, workflow.\n`
141+
`error: command-argument value 'invalid-arg' is invalid for argument 'type'. Allowed choices are project, build, deploy, infra, workflow, docs.\n`
142142
);
143143
expect(output).toEqual(``);
144144
expect(code).toEqual(1);
@@ -343,7 +343,7 @@ describe("e2e tests for manifest command", () => {
343343
});
344344

345345
expect(error).toBe(
346-
`error: command-argument value 'invalid-arg' is invalid for argument 'type'. Allowed choices are project, build, deploy, infra, workflow.\n`
346+
`error: command-argument value 'invalid-arg' is invalid for argument 'type'. Allowed choices are project, build, deploy, infra, workflow, docs.\n`
347347
);
348348
expect(output).toEqual(``);
349349
expect(code).toEqual(1);

packages/cli/src/__tests__/e2e/p1/no-command.spec.ts

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ Commands:
1717
infra|i [options] <action> Modular Infrastructure-As-Code Orchestrator
1818
manifest|m Inspect & Migrade Polywrap Manifests
1919
test|t [options] Execute Tests
20+
docs Documentation commands
2021
help [command] display help for command
2122
`;
2223

packages/cli/src/commands/docs.ts

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
import {
2+
defaultDocsManifest,
3+
defaultPolywrapManifest,
4+
intlMsg,
5+
parseLogFileOption,
6+
parseManifestFileOption,
7+
} from "../lib";
8+
import { getSchemaString } from "./manifest";
9+
import { BaseCommandOptions, Command, Program } from "./types";
10+
import { createLogger } from "./utils/createLogger";
11+
12+
import fse from "fs-extra";
13+
14+
const pathStr = intlMsg.commands_docs_init_m_path();
15+
const defaultManifestStr = defaultPolywrapManifest.join(" | ");
16+
17+
export interface DocsInitCommandOptions extends BaseCommandOptions {
18+
manifestFile: string;
19+
}
20+
21+
export const docs: Command = {
22+
setup: (program: Program) => {
23+
const docsCommand = program
24+
.command("docs")
25+
.description(intlMsg.commands_docs_description());
26+
27+
docsCommand
28+
.command("init")
29+
.alias("i")
30+
.description(intlMsg.commands_docs_init_description())
31+
.option(
32+
`-m, --manifest-file <${pathStr}>`,
33+
`${intlMsg.commands_docs_options_m({
34+
default: defaultManifestStr,
35+
})}`
36+
)
37+
.option("-v, --verbose", intlMsg.commands_common_options_verbose())
38+
.option("-q, --quiet", intlMsg.commands_common_options_quiet())
39+
.option(
40+
`-l, --log-file [${pathStr}]`,
41+
`${intlMsg.commands_build_options_l()}`
42+
)
43+
.action(async (options: Partial<DocsInitCommandOptions>) => {
44+
await runDocsInitCommand({
45+
manifestFile: parseManifestFileOption(
46+
options.manifestFile,
47+
defaultPolywrapManifest
48+
),
49+
dir: options.dir || false,
50+
force: options.force || false,
51+
logFile: parseLogFileOption(options.logFile),
52+
quiet: options.quiet || false,
53+
verbose: options.verbose || false,
54+
});
55+
});
56+
},
57+
};
58+
59+
export const runDocsInitCommand = async (
60+
options: Required<DocsInitCommandOptions>
61+
): Promise<void> => {
62+
const { verbose, quiet, logFile, manifestFile } = options;
63+
64+
const logger = createLogger({ verbose, quiet, logFile });
65+
66+
const docsManifestExists = fse.existsSync(defaultDocsManifest[0]);
67+
68+
if (docsManifestExists) {
69+
logger.error(
70+
intlMsg.commands_docs_init_error_manifest_exists({
71+
manifestFile: defaultDocsManifest[0],
72+
})
73+
);
74+
process.exit(1);
75+
}
76+
77+
const docsManifest = await getSchemaString(logger, "docs", {
78+
verbose: false,
79+
quiet: true,
80+
logFile: false,
81+
raw: false,
82+
manifestFile: false,
83+
});
84+
85+
fse.writeFileSync(defaultDocsManifest[0], docsManifest);
86+
87+
logger.info(
88+
intlMsg.commands_docs_init_msg_manifest_created({
89+
manifestFile: defaultDocsManifest[0],
90+
})
91+
);
92+
93+
logger.warn(
94+
intlMsg.commands_docs_init_warn_update_manifest({
95+
manifestFile,
96+
docsManifestFile: defaultDocsManifest[0],
97+
})
98+
);
99+
};

packages/cli/src/commands/index.ts

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ export * from "./infra";
77
export * from "./manifest";
88
export * from "./test";
99
export * from "./types";
10+
export * from "./docs";
1011

1112
import { BuildCommandOptions } from "./build";
1213
import { CodegenCommandOptions } from "./codegen";
@@ -25,6 +26,7 @@ import {
2526
ManifestType,
2627
} from "./manifest";
2728
import { TestCommandOptions } from "./test";
29+
import { DocsInitCommandOptions } from "./docs";
2830

2931
export interface CommandTypings {
3032
build: BuildCommandOptions;
@@ -67,4 +69,7 @@ export interface CommandTypings {
6769
};
6870
};
6971
test: TestCommandOptions;
72+
docs: {
73+
init: DocsInitCommandOptions;
74+
};
7075
}

0 commit comments

Comments
 (0)