From bddc5b58e2946c83a1c452ea8e68b6abf0a6608a Mon Sep 17 00:00:00 2001 From: Craigory Coppola Date: Fri, 21 May 2021 08:57:39 -0500 Subject: [PATCH] feat(repo): docs generator prints options --- docs/core/core.md | 42 ----------- docs/core/executors/app.md | 31 ++++++++ docs/core/executors/init.md | 3 + docs/core/executors/lib.md | 27 +++++++ docs/core/executors/nuget-reference.md | 37 +++++++++ docs/core/executors/project-reference.md | 13 ++++ docs/core/executors/restore.md | 1 + docs/core/executors/sync.md | 1 + docs/core/generators/app.md | 31 ++++++++ docs/core/generators/init.md | 3 + docs/core/generators/lib.md | 27 +++++++ docs/core/generators/nuget-reference.md | 37 +++++++++ docs/core/generators/project-reference.md | 13 ++++ docs/core/generators/restore.md | 1 + docs/core/generators/sync.md | 1 + docs/core/index.md | 53 +++++++++++++ docs/typescript/index.md | 1 + docs/typescript/typescript.md | 12 --- packages/core/src/generators/app/schema.json | 1 + packages/typescript/executors.json | 10 +-- packages/typescript/generators.json | 10 +-- tools/generators/generate-docs/index.ts | 75 +++++++++++++++---- .../generate-docs/schema-json.interface.ts | 21 +++++- .../templates/detail/__generatorFileName__.md | 14 ++++ .../__projectFileName__/index.md} | 16 +++- 25 files changed, 398 insertions(+), 83 deletions(-) delete mode 100644 docs/core/core.md create mode 100644 docs/core/executors/app.md create mode 100644 docs/core/executors/init.md create mode 100644 docs/core/executors/lib.md create mode 100644 docs/core/executors/nuget-reference.md create mode 100644 docs/core/executors/project-reference.md create mode 100644 docs/core/executors/restore.md create mode 100644 docs/core/executors/sync.md create mode 100644 docs/core/generators/app.md create mode 100644 docs/core/generators/init.md create mode 100644 docs/core/generators/lib.md create mode 100644 docs/core/generators/nuget-reference.md create mode 100644 docs/core/generators/project-reference.md create mode 100644 docs/core/generators/restore.md create mode 100644 docs/core/generators/sync.md create mode 100644 docs/core/index.md create mode 100644 docs/typescript/index.md delete mode 100644 docs/typescript/typescript.md create mode 100644 tools/generators/generate-docs/templates/detail/__generatorFileName__.md rename tools/generators/generate-docs/templates/{__projectFileName__/__projectFileName__.md => index/__projectFileName__/index.md} (52%) diff --git a/docs/core/core.md b/docs/core/core.md deleted file mode 100644 index 67f1884e..00000000 --- a/docs/core/core.md +++ /dev/null @@ -1,42 +0,0 @@ -# core - -## Generators - -### lib -nx-dotnet generator - -### app -Generate a new C# project. - -### project-reference -Adds a reference from one project to another. - -### init -init generator - -### sync -sync generator - -### nuget-reference -nuget-reference generator - -### restore -Restores NuGet packages and .NET tools used by the workspace - - -## Executors - -### build -build executor - -### serve -serve executor - -### test -test executor - -### publish -publish executor - -### format -Formats and lints a project using the dotnet-format tool diff --git a/docs/core/executors/app.md b/docs/core/executors/app.md new file mode 100644 index 00000000..4142e9a5 --- /dev/null +++ b/docs/core/executors/app.md @@ -0,0 +1,31 @@ +# app + +## NxDotnet Application Generator + +## Options + +### name (string) + +### tags (string) + +Add tags to the project (used for linting) + +### directory (string) + +A directory where the project is placed + +### template (string) + +The template to instantiate when the command is invoked. Each template might have specific options you can pass. + +### language (string) + +Which language should the project use? + +### testTemplate (string) + +Which template should be used for creating the tests project? + +### skipOutputPathManipulation (boolean) + +Skip XML changes for default build path diff --git a/docs/core/executors/init.md b/docs/core/executors/init.md new file mode 100644 index 00000000..40a86e17 --- /dev/null +++ b/docs/core/executors/init.md @@ -0,0 +1,3 @@ +# init + +## Initialize NxDotnet diff --git a/docs/core/executors/lib.md b/docs/core/executors/lib.md new file mode 100644 index 00000000..686fa632 --- /dev/null +++ b/docs/core/executors/lib.md @@ -0,0 +1,27 @@ +# lib + +## NxDotnet Library Generator + +## Options + +### name (string) + +### tags (string) + +Add tags to the project (used for linting) + +### directory (string) + +A directory where the project is placed + +### template (string) + +The template to instantiate when the command is invoked. Each template might have specific options you can pass. + +### language (string) + +Which language should the project use? + +### testTemplate (string) + +Which template should be used for creating the tests project? diff --git a/docs/core/executors/nuget-reference.md b/docs/core/executors/nuget-reference.md new file mode 100644 index 00000000..008ecd84 --- /dev/null +++ b/docs/core/executors/nuget-reference.md @@ -0,0 +1,37 @@ +# nuget-reference + +## Options + +### project (string) + +### packageName (string) + +Which package should be added? + +### version (string) + +The package version to add. + +### framework (string) + +Adds a package reference only when targeting a specific framework. + +### packageDirectory (string) + +The directory where to restore the packages. The default package restore location is %userprofile%\.nuget\packages on Windows and ~/.nuget/packages on macOS and Linux. For more information, see [Managing the global packages, cache, and temp folders in NuGet](https://docs.microsoft.com/en-us/nuget/consume-packages/managing-the-global-packages-and-cache-folders). + +### prerelease (boolean) + +Allows prerelease packages to be installed. Available since .NET Core 5 SDK + +### source (string) + +The URI of the NuGet package source to use during the restore operation. + +### noRestore (boolean) + +Adds a package reference without performing a restore preview and compatibility check. + +### allowVersionMismatch (boolean) + +Ignores single version principle for this package across all apps in the workspace diff --git a/docs/core/executors/project-reference.md b/docs/core/executors/project-reference.md new file mode 100644 index 00000000..39282754 --- /dev/null +++ b/docs/core/executors/project-reference.md @@ -0,0 +1,13 @@ +# project-reference + +## NxDotnet Application Generator + +## Options + +### project (string) + +Host project + +### reference (string) + +Source project diff --git a/docs/core/executors/restore.md b/docs/core/executors/restore.md new file mode 100644 index 00000000..2255cbb0 --- /dev/null +++ b/docs/core/executors/restore.md @@ -0,0 +1 @@ +# restore diff --git a/docs/core/executors/sync.md b/docs/core/executors/sync.md new file mode 100644 index 00000000..6de99032 --- /dev/null +++ b/docs/core/executors/sync.md @@ -0,0 +1 @@ +# sync diff --git a/docs/core/generators/app.md b/docs/core/generators/app.md new file mode 100644 index 00000000..4142e9a5 --- /dev/null +++ b/docs/core/generators/app.md @@ -0,0 +1,31 @@ +# app + +## NxDotnet Application Generator + +## Options + +### name (string) + +### tags (string) + +Add tags to the project (used for linting) + +### directory (string) + +A directory where the project is placed + +### template (string) + +The template to instantiate when the command is invoked. Each template might have specific options you can pass. + +### language (string) + +Which language should the project use? + +### testTemplate (string) + +Which template should be used for creating the tests project? + +### skipOutputPathManipulation (boolean) + +Skip XML changes for default build path diff --git a/docs/core/generators/init.md b/docs/core/generators/init.md new file mode 100644 index 00000000..40a86e17 --- /dev/null +++ b/docs/core/generators/init.md @@ -0,0 +1,3 @@ +# init + +## Initialize NxDotnet diff --git a/docs/core/generators/lib.md b/docs/core/generators/lib.md new file mode 100644 index 00000000..686fa632 --- /dev/null +++ b/docs/core/generators/lib.md @@ -0,0 +1,27 @@ +# lib + +## NxDotnet Library Generator + +## Options + +### name (string) + +### tags (string) + +Add tags to the project (used for linting) + +### directory (string) + +A directory where the project is placed + +### template (string) + +The template to instantiate when the command is invoked. Each template might have specific options you can pass. + +### language (string) + +Which language should the project use? + +### testTemplate (string) + +Which template should be used for creating the tests project? diff --git a/docs/core/generators/nuget-reference.md b/docs/core/generators/nuget-reference.md new file mode 100644 index 00000000..008ecd84 --- /dev/null +++ b/docs/core/generators/nuget-reference.md @@ -0,0 +1,37 @@ +# nuget-reference + +## Options + +### project (string) + +### packageName (string) + +Which package should be added? + +### version (string) + +The package version to add. + +### framework (string) + +Adds a package reference only when targeting a specific framework. + +### packageDirectory (string) + +The directory where to restore the packages. The default package restore location is %userprofile%\.nuget\packages on Windows and ~/.nuget/packages on macOS and Linux. For more information, see [Managing the global packages, cache, and temp folders in NuGet](https://docs.microsoft.com/en-us/nuget/consume-packages/managing-the-global-packages-and-cache-folders). + +### prerelease (boolean) + +Allows prerelease packages to be installed. Available since .NET Core 5 SDK + +### source (string) + +The URI of the NuGet package source to use during the restore operation. + +### noRestore (boolean) + +Adds a package reference without performing a restore preview and compatibility check. + +### allowVersionMismatch (boolean) + +Ignores single version principle for this package across all apps in the workspace diff --git a/docs/core/generators/project-reference.md b/docs/core/generators/project-reference.md new file mode 100644 index 00000000..39282754 --- /dev/null +++ b/docs/core/generators/project-reference.md @@ -0,0 +1,13 @@ +# project-reference + +## NxDotnet Application Generator + +## Options + +### project (string) + +Host project + +### reference (string) + +Source project diff --git a/docs/core/generators/restore.md b/docs/core/generators/restore.md new file mode 100644 index 00000000..2255cbb0 --- /dev/null +++ b/docs/core/generators/restore.md @@ -0,0 +1 @@ +# restore diff --git a/docs/core/generators/sync.md b/docs/core/generators/sync.md new file mode 100644 index 00000000..6de99032 --- /dev/null +++ b/docs/core/generators/sync.md @@ -0,0 +1 @@ +# sync diff --git a/docs/core/index.md b/docs/core/index.md new file mode 100644 index 00000000..58bb1c11 --- /dev/null +++ b/docs/core/index.md @@ -0,0 +1,53 @@ +# core + +## Generators + +### [lib](./generators/lib.md) + +nx-dotnet generator + +### [app](./generators/app.md) + +Generate a new C# project. + +### [project-reference](./generators/project-reference.md) + +Adds a reference from one project to another. + +### [init](./generators/init.md) + +init generator + +### [sync](./generators/sync.md) + +sync generator + +### [nuget-reference](./generators/nuget-reference.md) + +nuget-reference generator + +### [restore](./generators/restore.md) + +Restores NuGet packages and .NET tools used by the workspace + +## Executors + +### [build](./executors/build.md) + +build executor + +### [serve](./executors/serve.md) + +serve executor + +### [test](./executors/test.md) + +test executor + +### [publish](./executors/publish.md) + +publish executor + +### [format](./executors/format.md) + +Formats and lints a project using the dotnet-format tool diff --git a/docs/typescript/index.md b/docs/typescript/index.md new file mode 100644 index 00000000..53884844 --- /dev/null +++ b/docs/typescript/index.md @@ -0,0 +1 @@ +# typescript diff --git a/docs/typescript/typescript.md b/docs/typescript/typescript.md deleted file mode 100644 index c5fb16ea..00000000 --- a/docs/typescript/typescript.md +++ /dev/null @@ -1,12 +0,0 @@ -# typescript - -## Generators - -### typescript -typescript generator - - -## Executors - -### build -build executor diff --git a/packages/core/src/generators/app/schema.json b/packages/core/src/generators/app/schema.json index 964be756..87525860 100644 --- a/packages/core/src/generators/app/schema.json +++ b/packages/core/src/generators/app/schema.json @@ -43,6 +43,7 @@ "type": "string", "description": "Which template should be used for creating the tests project?", "default": "nunit", + "enum": ["nunit", "xunit", "mstest", "none"], "x-prompt": { "message": "Which template should be used for creating the tests project", "type": "list", diff --git a/packages/typescript/executors.json b/packages/typescript/executors.json index b92c873c..e9802d07 100644 --- a/packages/typescript/executors.json +++ b/packages/typescript/executors.json @@ -1,10 +1,10 @@ { "$schema": "http://json-schema.org/schema", "executors": { - "build": { - "implementation": "./src/executors/build/executor", - "schema": "./src/executors/build/schema.json", - "description": "build executor" - } + // "build": { + // "implementation": "./src/executors/build/executor", + // "schema": "./src/executors/build/schema.json", + // "description": "build executor" + // } } } diff --git a/packages/typescript/generators.json b/packages/typescript/generators.json index e4c33b48..9e730962 100644 --- a/packages/typescript/generators.json +++ b/packages/typescript/generators.json @@ -3,10 +3,10 @@ "name": "typescript", "version": "0.0.1", "generators": { - "typescript": { - "factory": "./src/generators/typescript/generator", - "schema": "./src/generators/typescript/schema.json", - "description": "typescript generator" - } + // "typescript": { + // "factory": "./src/generators/typescript/generator", + // "schema": "./src/generators/typescript/schema.json", + // "description": "typescript generator" + // } } } diff --git a/tools/generators/generate-docs/index.ts b/tools/generators/generate-docs/index.ts index 6bd89c37..87b6ef4a 100644 --- a/tools/generators/generate-docs/index.ts +++ b/tools/generators/generate-docs/index.ts @@ -1,28 +1,77 @@ import { Tree, - formatFiles, - installPackagesTask, getProjects, ProjectConfiguration, - NxJsonProjectConfiguration, generateFiles, names, readJson, } from '@nrwl/devkit'; -import { libraryGenerator } from '@nrwl/workspace/generators'; + import * as path from 'path'; -import { ExecutorsCollection, GeneratorsCollection } from './schema-json.interface'; +import { + ExecutorsCollection, + GeneratorsCollection, + SchemaJSON, +} from './schema-json.interface'; export default async function (host: Tree, schema: any) { const projects = await findProjectsWithGeneratorsOrExecutors(host); - projects.forEach((p) => { - const generators = readJson(host, `${p.root}/generators.json`); - const executors = readJson(host, `${p.root}/executors.json`); - generateFiles(host, path.join(__dirname, 'templates'), `docs`, { - projectFileName: names(p.name).fileName, - project: p, - generators: generators.generators, - executors: executors.executors + projects.forEach((project) => { + const generators = readJson( + host, + `${project.root}/generators.json`, + ).generators; + const executors = readJson( + host, + `${project.root}/executors.json`, + ).executors; + const projectFileName = names(project.name).fileName; + + generateFiles(host, path.join(__dirname, 'templates/index'), `docs`, { + projectFileName, + project, + generators, + executors, + }); + + Object.entries(generators).forEach(([generatorName, config]) => { + const generatorFileName = names(generatorName).fileName; + const schema = readJson( + host, + path.relative(process.cwd(), path.resolve(project.root, config.schema)), + ); + generateFiles( + host, + path.join(__dirname, 'templates/detail'), + `docs/${projectFileName}/generators`, + { + projectFileName, + project, + generatorName, + generatorFileName, + schema, + }, + ); + }); + + Object.entries(generators).forEach(([generatorName, config]) => { + const generatorFileName = names(generatorName).fileName; + const schema = readJson( + host, + path.relative(process.cwd(), path.resolve(project.root, config.schema)), + ); + generateFiles( + host, + path.join(__dirname, 'templates/detail'), + `docs/${projectFileName}/executors`, + { + projectFileName, + project, + generatorName, + generatorFileName, + schema, + }, + ); }); }); } diff --git a/tools/generators/generate-docs/schema-json.interface.ts b/tools/generators/generate-docs/schema-json.interface.ts index 049cc4c9..57912064 100644 --- a/tools/generators/generate-docs/schema-json.interface.ts +++ b/tools/generators/generate-docs/schema-json.interface.ts @@ -1,10 +1,27 @@ -export interface SchemaJSON {} +export interface SchemaJSON { + title: string; + description: string; + properties: { [key: string]: PropertyConfiguration }; + required: string[]; +} + +export interface PropertyConfiguration { + type: string; + description: string; + alias: string[]; + anyOf?: PropertyConfiguration[]; + items: { + type: string; + }; + default: boolean | string | number; + enum: string[]; +} export interface GeneratorsCollection { name: string; version: string; generators: { - [key: string]: GeneratorConfiguration + [key: string]: GeneratorConfiguration; }; } diff --git a/tools/generators/generate-docs/templates/detail/__generatorFileName__.md b/tools/generators/generate-docs/templates/detail/__generatorFileName__.md new file mode 100644 index 00000000..f0303b85 --- /dev/null +++ b/tools/generators/generate-docs/templates/detail/__generatorFileName__.md @@ -0,0 +1,14 @@ +# <%= generatorName %> + +<%if(schema.title){%> + +## <%= schema.title %><%}%> + +<% if(Object.values(schema.properties).length > 0) {%> + +## Options <% Object.entries(schema.properties).forEach(([property, config]) => {%> + +### <%= property%> (<%=config.type%>) + +<%= config.description %> +<% })} %> diff --git a/tools/generators/generate-docs/templates/__projectFileName__/__projectFileName__.md b/tools/generators/generate-docs/templates/index/__projectFileName__/index.md similarity index 52% rename from tools/generators/generate-docs/templates/__projectFileName__/__projectFileName__.md rename to tools/generators/generate-docs/templates/index/__projectFileName__/index.md index c8d28ff1..2ce13447 100644 --- a/tools/generators/generate-docs/templates/__projectFileName__/__projectFileName__.md +++ b/tools/generators/generate-docs/templates/index/__projectFileName__/index.md @@ -1,13 +1,21 @@ # <%= project.name %> +<% if(Object.values(executors).length > 0) {%> + ## Generators + <% Object.entries(generators).forEach(([key, config]) => { %> -### <%= key %> + +### [<%= key %>](./generators/<%=key%>.md) + <%= config.description %> -<% }) %> +<% })} %><% if(Object.values(executors).length > 0) {%> ## Executors + <% Object.entries(executors).forEach(([key, config]) => { %> -### <%= key %> + +### [<%= key %>](./executors/<%=key%>.md) + <%= config.description %> -<% }) %> \ No newline at end of file +<% })} %>