feat(nxdoc): include getting started text

nx-dotnet · May 23, 2021 · db3ec62 · db3ec62
1 parent b0bf601
commit db3ec62
Show file tree

Hide file tree

Showing 12 changed files with 174 additions and 20 deletions.
diff --git a/docs/core/executors/test.md b/docs/core/executors/test.md
@@ -1,6 +1,8 @@
 # @nx-dotnet/core:test
 
-## Runs test via the dotnet cli
+## NxDotnet Test Executor
+
+Runs test via the dotnet cli
 
 ## Options
 

diff --git a/docs/core/index.md b/docs/core/index.md
@@ -6,6 +6,48 @@ slug: /core/
 
 # Getting Started
 
+## Prerequisites
+
+- Have an existing nx workspace. For creating this, see [nrwl&#39;s documentation](https://nx.dev/latest/angular/getting-started/nx-setup).
+- .NET SDK is installed, and `dotnet` is available on the path. For help on this, see [Microsoft&#39;s documentation](https://dotnet.microsoft.com/learn/dotnet/hello-world-tutorial/install)
+
+## Installation
+
+### NPM
+
+```shell
+npm i --save-dev @nx-dotnet/core
+npx nx g @nx-dotnet/core:init
+```
+
+### PNPM
+
+```shell
+pnpm i --save-dev @nx-dotnet/core
+pnpx nx g @nx-dotnet/core:init
+```
+
+### Yarn
+
+```shell
+yarn add --dev @nx-dotnet/core
+npx nx g @nx-dotnet/core:init
+```
+
+## Generate and run your first api!
+
+Generate my-api, and my-api-test with C# and nunit tests.
+
+```shell
+npx nx g @nx-dotnet/core:app my-api --test-template nunit --language C#
+```
+
+Run my-api locally
+
+```shell
+npx nx serve my-api
+```
+
 # API Reference
 
 ## Generators

diff --git a/docs/nxdoc/generators/generate-docs.md b/docs/nxdoc/generators/generate-docs.md
@@ -4,4 +4,16 @@
 
 ### outputDirectory (string)
 
+Where should the generated docs be placed?
+
+### gettingStartedFile (string)
+
+File contents to place before the API reference section for each package. &lt;src&gt; is replaced by the package&#39;s root.
+
 ### skipFrontMatter (boolean)
+
+Nxdoc generates frontmatter suitable for docusaurus by default.
+
+### skipFormat (boolean)
+
+Skips running the output through prettier
diff --git a/docs/nxdoc/index.md b/docs/nxdoc/index.md
@@ -6,6 +6,14 @@ slug: /nxdoc/
 
 # Getting Started
 
+# nxdoc
+
+This library was generated with [Nx](https://nx.dev).
+
+## Running unit tests
+
+Run `nx test nxdoc` to execute the unit tests via [Jest](https://jestjs.io).
+
 # API Reference
 
 ## Generators

diff --git a/docs/typescript/index.md b/docs/typescript/index.md
@@ -6,4 +6,12 @@ slug: /typescript/
 
 # Getting Started
 
+# typescript
+
+This library was generated with [Nx](https://nx.dev).
+
+## Running unit tests
+
+Run `nx test typescript` to execute the unit tests via [Jest](https://jestjs.io).
+
 # API Reference
diff --git a/packages/core/README.md b/packages/core/README.md
@@ -1,7 +1,41 @@
-# nx-dotnet
+## Prerequisites
 
-This library was generated with [Nx](https://nx.dev).
+- Have an existing nx workspace. For creating this, see [nrwl's documentation](https://nx.dev/latest/angular/getting-started/nx-setup).
+- .NET SDK is installed, and `dotnet` is available on the path. For help on this, see [Microsoft's documentation](https://dotnet.microsoft.com/learn/dotnet/hello-world-tutorial/install)
 
-## Running unit tests
+## Installation
 
-Run `nx test nx-dotnet` to execute the unit tests via [Jest](https://jestjs.io).
+### NPM
+
+```shell
+npm i --save-dev @nx-dotnet/core
+npx nx g @nx-dotnet/core:init
+```
+
+### PNPM
+
+```shell
+pnpm i --save-dev @nx-dotnet/core
+pnpx nx g @nx-dotnet/core:init
+```
+
+### Yarn
+
+```shell
+yarn add --dev @nx-dotnet/core
+npx nx g @nx-dotnet/core:init
+```
+
+## Generate and run your first api!
+
+Generate my-api, and my-api-test with C# and nunit tests.
+
+```shell
+npx nx g @nx-dotnet/core:app my-api --test-template nunit --language C#
+```
+
+Run my-api locally
+
+```shell
+npx nx serve my-api
+```
diff --git a/packages/core/src/executors/test/schema.json b/packages/core/src/executors/test/schema.json
@@ -1,8 +1,8 @@
 {
   "$schema": "http://json-schema.org/schema",
   "cli": "nx",
-  "title": "Runs test via the dotnet cli",
-  "description": "",
+  "title": "NxDotnet Test Executor",
+  "description": "Runs test via the dotnet cli",
   "type": "object",
   "properties": {
     "testAdapterPath": {

diff --git a/packages/nxdoc/src/generators/generate-docs/generator.ts b/packages/nxdoc/src/generators/generate-docs/generator.ts
@@ -1,14 +1,16 @@
 import {
-  Tree,
-  getProjects,
-  ProjectConfiguration,
+  formatFiles,
   generateFiles,
+  getProjects,
   names,
+  ProjectConfiguration,
   readJson,
-  formatFiles,
+  Tree,
 } from '@nrwl/devkit';
 
+import { readFileSync } from 'fs';
 import * as path from 'path';
+
 import { Schema } from './schema';
 import {
   ExecutorsCollection,
@@ -19,9 +21,20 @@ import {
 export default async function (host: Tree, options: Schema) {
   const projects = await findProjectsWithGeneratorsOrExecutors(host);
 
-  const packageDetails: {packageName: string, projectFileName: string, project: Omit<ProjectConfiguration, 'generators'>, generators: number, executors: number}[] = [];
+  const packageDetails: {
+    packageName: string;
+    projectFileName: string;
+    project: Omit<ProjectConfiguration, 'generators'>;
+    generators: number;
+    executors: number;
+  }[] = [];
 
   projects.forEach((project) => {
+    const gettingStartedFile = options.gettingStartedFile.replace(
+      '<src>',
+      project.root,
+    );
+
     const generators = project.generators
       ? readJson<GeneratorsCollection>(host, `${project.root}/generators.json`)
           .generators
@@ -34,7 +47,13 @@ export default async function (host: Tree, options: Schema) {
     const packageName = readJson(host, `${project.root}/package.json`).name;
     const projectFileName = names(project.name).fileName;
 
-    packageDetails.push({packageName, projectFileName, project, generators: Object.keys(generators).length, executors: Object.keys(executors).length})
+    packageDetails.push({
+      packageName,
+      projectFileName,
+      project,
+      generators: Object.keys(generators).length,
+      executors: Object.keys(executors).length,
+    });
 
     generateFiles(
       host,
@@ -47,6 +66,9 @@ export default async function (host: Tree, options: Schema) {
         generators,
         executors,
         underscore: '_',
+        gettingStartedMd: options.gettingStartedFile
+          ? readFileSync(gettingStartedFile).toString()
+          : '',
         frontMatter: options.skipFrontMatter
           ? null
           : {
@@ -99,12 +121,19 @@ export default async function (host: Tree, options: Schema) {
     });
   });
 
-  generateFiles(host, path.join(__dirname, 'templates/root'), options.outputDirectory, ({
-    packageDetails,
-    includeFrontMatter: !options.skipFrontMatter
-  }))
+  generateFiles(
+    host,
+    path.join(__dirname, 'templates/root'),
+    options.outputDirectory,
+    {
+      packageDetails,
+      includeFrontMatter: !options.skipFrontMatter,
+    },
+  );
 
-  formatFiles(host);
+  if (!options.skipFormat) {
+    formatFiles(host);
+  }
 }
 
 export async function findProjectsWithGeneratorsOrExecutors(host: Tree) {

diff --git a/packages/nxdoc/src/generators/generate-docs/schema.d.ts b/packages/nxdoc/src/generators/generate-docs/schema.d.ts
@@ -1,4 +1,6 @@
 export interface Schema {
   outputDirectory: string;
   skipFrontMatter: boolean;
+  skipFormat: boolean;
+  gettingStartedFile: string;
 }
diff --git a/packages/nxdoc/src/generators/generate-docs/schema.json b/packages/nxdoc/src/generators/generate-docs/schema.json
@@ -5,10 +5,22 @@
   "properties": {
     "outputDirectory": {
       "type": "string",
+      "description": "Where should the generated docs be placed?",
       "default": "docs"
     },
+    "gettingStartedFile": {
+      "type": "string",
+      "description": "File contents to place before the API reference section for each package. <src> is replaced by the package's root.",
+      "default": "<src>/readme.md"
+    },
     "skipFrontMatter": {
       "type": "boolean",
+      "description": "Nxdoc generates frontmatter suitable for docusaurus by default.",
+      "default": false
+    },
+    "skipFormat": {
+      "type": "boolean",
+      "description": "Skips running the output through prettier",
       "default": false
     }
   },

diff --git a/...nxdoc/src/generators/generate-docs/templates/index/__projectFileName__/index.md b/...nxdoc/src/generators/generate-docs/templates/index/__projectFileName__/index.md
@@ -4,7 +4,9 @@ sidebar_position: 0
 slug: /<%=projectFileName%>/
 <%}%>---
 
-# Getting Started
+<%if (gettingStartedMd && gettingStartedMd.length) {%># Getting Started
+<%=gettingStartedMd%>
+<%}%>
 
 # API Reference
 

diff --git a/tools/generators/generate-docs/index.ts b/tools/generators/generate-docs/index.ts
@@ -6,6 +6,9 @@ export default async function (host: Tree, schema: any) {
   execSync('nx build nxdoc');
   const path = resolve('dist/packages/nxdoc/src');
   const generateDocs = require(path).generateDocs;
-  await generateDocs(host, { outputDirectory: 'docs' });
+  await generateDocs(host, {
+    outputDirectory: 'docs',
+    gettingStartedFile: '<src>/readme.md',
+  });
   await formatFiles(host);
 }