feat(docs): Add a bunch of docs

.gitignore

@@ -22,7 +22,7 @@ docs/data/build.json
 !docs/content/docs/typescript-api/_index.md
 docs/content/docs/graphql-api/*
 docs/content/docs/plugins/*
-!docs/content/docs/plugins/*.md
+!docs/content/docs/plugins/*.*
 !docs/content/docs/graphql-api/_index.md
 !docs/content/docs/graphql-api/shop/_index.md
 !docs/content/docs/graphql-api/admin/_index.md

docs/content/docs/developer-guide/_index.md

@@ -6,4 +6,4 @@ showtoc: false
  
 # Developer Guide
 
-This section contains guides for developers building applications which consume the Vendure API. The primary focus is on the use of the Shop API, since the Admin API functions are covered by the admin-ui-plugin.
+This section contains guides for developers building applications with Vendure.

docs/content/docs/developer-guide/authentication-and-sessions.md

@@ -1,6 +1,5 @@
 ---
 title: "Authentication & Sessions"
-weight: 0
 showtoc: true
 ---
  

docs/content/docs/developer-guide/customizing-models.md

@@ -1,6 +1,5 @@
 ---
 title: "Customizing Models"
-weight: 0
 showtoc: true
 ---
  
@@ -34,4 +33,4 @@ With the example config above, the following will occur:
 
 1. The database schema will be altered and a column will be added for each custom field. Note: this step requires the [TypeORM synchronize option](https://typeorm.io/#/connection-options/common-connection-options) to be set to `true` as above.
 2. The GraphQL APIs will be modified on bootstrap to add the custom fields to the `Product` and `User` types respectively.
-3. If you are using the [admin-ui-plugin]({{< relref "docs/plugins/admin-ui-plugin" >}}), the Admin UI detail pages will now contain form inputs to allow the custom field data to be added or edited.
+3. If you are using the [admin-ui-plugin]({{< relref "/docs/plugins/admin-ui-plugin" >}}), the Admin UI detail pages will now contain form inputs to allow the custom field data to be added or edited.

docs/content/docs/developer-guide/deployment.md

@@ -0,0 +1,17 @@
+---
+title: "Deployment"
+showtoc: true
+---
+
+# Deploying a Vendure Application
+
+A Vendure application is essentially a Node.js application, and can be deployed to any environment that supports Node.js.
+
+The bare minimum requirements are:
+
+* A server with Node.js installed
+* A database server (if using MySQL/Postgres)
+
+A typical pattern is to run the Vendure app on the server, e.g. at `http://localhost:3000` an then use [nginx as a reverse proxy](https://docs.nginx.com/nginx/admin-guide/web-server/reverse-proxy/) to direct requests from the Internet to the Vendure application.
+
+Here is a good guide to setting up a production-ready server for an app such as Vendure: https://www.digitalocean.com/community/tutorials/how-to-set-up-a-node-js-application-for-production-on-ubuntu-18-04

docs/content/docs/developer-guide/overview/_index.md

@@ -0,0 +1,35 @@
+---
+title: "Architecture Overview"
+weight: 0
+showtoc: true
+---
+
+# Vendure Architecture Overview
+
+Vendure is built with an internal architecture based on [NestJS modules](https://docs.nestjs.com/modules). It is not necessary to be familiar with all the internal modules, but a simplified overview can help to see how the major parts fit together.
+Here is a simplified diagram of the Vendure application architecture:
+
+{{< figure src="./vendure_architecture.png" >}} 
+
+## Entry Points
+
+As you can see in the diagram, there are two entry points into the application: [`bootstrap()`]({{< relref "bootstrap" >}}) and [`bootstrapWorker()`]({{< relref "bootstrap-worker" >}}), which start the main server and the [worker]({{< relref "vendure-worker" >}}) respectively.
+
+## GraphQL APIs
+
+There are 2 separate GraphQL APIs: shop and admin. 
+
+* The **Shop API** is used by public-facing client applications (web shops, e-commerce apps, mobile apps etc.) to allow customers to find products and place orders. 
+    
+    [Shop API Documentation]({{< relref "/docs/graphql-api/shop" >}}).
+* The **Admin API** is used by administrators to manage products, customers and orders. 
+
+    [Admin API Documentation]({{< relref "/docs/graphql-api/admin" >}}).
+
+## Database
+
+Vendure supports multiple databases. Currently it is tested with MySQL/MariaDB, PostgreSQL, SQLite and SQL.js. Since Vendure uses [TypeORM](https://typeorm.io/#/) to manage data access, it can theoretically also work with CockroachDB, Microsoft SQL Server and MongoDB, though these are as yet untested.
+
+## Custom Business Logic (Plugins)
+
+Not shown on the diagram (for the sake of simplicity) are plugins. Plugins are the mechanism by which you extend Vendure with your own business logic and functionality. See [the Plugins docs]({{< relref "/docs/plugins" >}})

docs/content/docs/developer-guide/vendure-worker.md

@@ -1,19 +1,28 @@
 ---
 title: "Vendure Worker"
-weight: 0
 showtoc: true
 ---
 
 # Vendure Worker
-
+ 
 The Vendure Worker is a process which is responsible for running computationally intensive or otherwise long-running tasks in the background. For example updating a search index or performing image transformations.
 
-The worker is started by calling the `bootstrapWorker()` function with the same configuration as is passed to the main server `bootstrap()`:
+The worker is started by calling the [`bootstrapWorker()`]({{< relref "bootstrap-worker" >}}) function with the same configuration as is passed to the main server `bootstrap()`:
 
 ```TypeScript
-import { bootstrapWorker } from '@vendure/core';
-
-import { config } from './vendure-config';
+import { Transport } from '@nest/microservices';
+import { bootstrapWorker, VendureConfig } from '@vendure/core';
+
+const config: VendureConfig = {
+    // ...
+    workerOptions: {
+        transport: Transport.TCP,
+        options: {
+            host: 'localhost',
+            port: 4242,
+        },
+    },
+};
 
 bootstrapWorker(config).catch(err => {
     console.log(err);

docs/content/docs/plugins/_index.md

@@ -6,7 +6,7 @@ showtoc: false
  
 # Plugins
 
-Plugins in Vendure allow one to:
+Plugins are the method by which the built-in functionality of Vendure can be extended. Plugins in Vendure allow one to:
 
 1. Modify the [VendureConfig]({{< relref "vendure-config" >}}) object.
 2. Extend the GraphQL API, including modifying existing types and adding completely new queries and mutations.
@@ -16,3 +16,15 @@ Plugins in Vendure allow one to:
 These abilities make plugins a very versatile and powerful means of implementing custom business requirements.
 
 This section details the official Vendure plugins included in the main Vendure repo, as well as a guide on writing your own plugins for Vendure.
+
+## Plugin Architecture
+
+{{< figure src="plugin_architecture.png" >}}
+
+This diagram illustrates the how a plugin can integrate with and extend Vendure.
+
+1. A Plugin may define logic to be run by the Vendure Worker. This is suitable for long-running or resource-intensive tasks and is done by providing controllers via the [`VendurePlugin.defineWorkers()` method]({{< relref "vendure-plugin" >}}#defineworkers).
+2. A Plugin can modify any aspect of server configuration via the [`VendurePlugin.configure()` method]({{< relref "vendure-plugin" >}}#configure).
+3. A Plugin can extend the GraphQL APIs via the [`VendurePlugin.extendShopAPI()` method]({{< relref "vendure-plugin" >}}#extendshopapi) and the [`VendurePlugin.extendAdminAPI()` method]({{< relref "vendure-plugin" >}}#extendadminapi).
+4. A Plugin has full access to the ServiceModule, which means it may inject and of the core Vendure services (which are responsible for all interaction with the database as well as business logic). Additionally a plugin may define its own services via the [`VendurePlugin.defineProviders()` method]({{< relref "vendure-plugin" >}}#defineproviders) and may define new database entities via the [`VendurePlugin.defineEntities()` method]({{< relref "vendure-plugin" >}}#defineentities).
+5. A Plugin can run arbitrary code, which allows it to make use of external services. For example, a plugin could interface with a cloud storage provider, a payment gateway, or a video encoding service.

docs/diagrams/plugin-architecture.puml

@@ -0,0 +1,46 @@
+@startuml
+!include theme.puml
+title Vendure Plugin Architecture
+
+
+
+package "@vendure/core" {
+    component VendureServer <<Vendure Server>> [
+        AppModule
+    ]
+    component VendureWorker <<Vendure Worker>> [
+        WorkerModule
+    ]
+    [ServiceModule] #efefef
+    [ApiModule] #efefef
+}
+
+cloud "GraphQL API" {
+    [Shop API] #ff88c1
+    [Admin API] #ff88c1
+}
+
+component VendurePlugin #ccffcc
+
+cloud "Internet" {
+    [External Service]
+}
+
+database "Database" {
+}
+
+[VendureServer] ---> [ServiceModule]
+[VendureServer] --> [ApiModule]
+[VendureWorker] --> [ServiceModule]
+[VendureWorker] <.right.> [VendureServer]
+[ApiModule] <...> [Shop API]
+[ApiModule] <...> [Admin API]
+[ServiceModule] <..> Database
+
+VendurePlugin .left.> VendureWorker #88cc88 : 1
+VendurePlugin ..> VendureServer #88cc88 : 2
+VendurePlugin .left.> ApiModule #88cc88 : 3
+VendurePlugin <..> ServiceModule #88cc88 : 4
+VendurePlugin <..> [External Service] #88cc88 : 5
+
+@enduml

docs/diagrams/vendure-architecture.puml

@@ -0,0 +1,46 @@
+@startuml
+!include theme.puml
+title Vendure Architecture
+
+interface "." as bootstrap
+interface "." as bootstrapWorker
+
+
+package "@vendure/core" {
+    component VendureServer <<Vendure Server>> [
+        AppModule
+    ]
+    component VendureWorker <<Vendure Worker>> [
+        WorkerModule
+    ]
+    [ServiceModule] #efefef
+    [ApiModule] #efefef
+}
+
+cloud "GraphQL API" {
+    [Shop API] #ff88c1
+    [Admin API] #ff88c1
+}
+
+database "Database" {
+component dbTypes #f3fff3 [
+MySQL/MariaDB
+PostgreSQL
+SQLite
+]
+}
+
+'note bottom of Database : MySQL/MariaDB, PostgreSQL, SQLite
+note top of bootstrap : bootstrap()
+note top of bootstrapWorker : bootstrapWorker()
+bootstrap -down- [VendureServer]
+bootstrapWorker -down- [VendureWorker]
+[VendureServer] ---> [ServiceModule]
+[VendureServer] --> [ApiModule]
+[VendureWorker] --> [ServiceModule]
+[VendureWorker] <.left.> [VendureServer]
+[ApiModule] <...> [Shop API]
+[ApiModule] <...> [Admin API]
+[ServiceModule] <..> dbTypes
+
+@enduml

package.json

@@ -5,7 +5,7 @@
   "scripts": {
     "core:watch": "concurrently -n tsc,gulp,common \"cd packages/core && yarn tsc:watch\" \"cd packages/core && yarn gulp:watch\" \"cd packages/common && yarn watch\"",
     "bootstrap": "lerna bootstrap && cd admin-ui && yarn",
-    "docs:watch": "concurrently -n docgen,hugo,webpack -c green,blue,cyan \"yarn generate-graphql-docs && yarn generate-typescript-docs -w\" \"cd docs && hugo server\" \"cd docs && yarn webpack -w\"",
+    "docs:watch": "concurrently --restart-tries 5 -n docgen,hugo,webpack -c green,blue,cyan \"yarn generate-graphql-docs && yarn generate-typescript-docs -w\" \"cd docs && hugo server\" \"cd docs && yarn webpack -w\"",
     "docs:build": "yarn generate-graphql-docs && yarn generate-typescript-docs && cd docs && yarn webpack --prod && node build.js && hugo",
     "docs:deploy": "cd docs && yarn && cd .. && yarn docs:build",
     "codegen": "ts-node scripts/codegen/generate-graphql-types.ts",

packages/core/src/bootstrap.ts

@@ -16,7 +16,20 @@ import { logProxyMiddlewares } from './plugin/plugin-utils';
 export type VendureBootstrapFunction = (config: VendureConfig) => Promise<INestApplication>;
 
 /**
- * Bootstrap the Vendure server.
+ * @description
+ * Bootstraps the Vendure server. This is the entry point to the application.
+ *
+ * @example
+ * ```TypeScript
+ * import { bootstrap } from '\@vendure/core';
+ * import { config } from './vendure-config';
+ *
+ * bootstrap(config).catch(err => {
+ *     console.log(err);
+ * });
+ * ```
+ * @docsCategory
+ * @docsWeight 0
  */
 export async function bootstrap(userConfig: Partial<VendureConfig>): Promise<INestApplication> {
     const config = await preBootstrapConfig(userConfig);
@@ -48,7 +61,21 @@ export async function bootstrap(userConfig: Partial<VendureConfig>): Promise<INe
 }
 
 /**
- * Bootstrap the Vendure worker.
+ * @description
+ * Bootstraps the Vendure worker. Read more about the [Vendure Worker]({{< relref "vendure-worker" >}}) or see the worker-specific options
+ * defined in {@link WorkerOptions}.
+ *
+ * @example
+ * ```TypeScript
+ * import { bootstrapWorker } from '\@vendure/core';
+ * import { config } from './vendure-config';
+ *
+ * bootstrapWorker(config).catch(err => {
+ *     console.log(err);
+ * });
+ * ```
+ * @docsCategory worker
+ * @docsWeight 0
  */
 export async function bootstrapWorker(userConfig: Partial<VendureConfig>): Promise<INestMicroservice> {
     if (userConfig.workerOptions && userConfig.workerOptions.runInMainProcess === true) {

packages/core/src/config/vendure-config.ts

@@ -374,7 +374,7 @@ export interface WorkerOptions {
  * [`VendureConfig`](https://github.com/vendure-ecommerce/vendure/blob/master/server/src/config/vendure-config.ts) interface.
  *
  * @docsCategory
- * @docsWeight 0
+ * @docsWeight 1
  */
 export interface VendureConfig {
     /**

packages/elasticsearch-plugin/src/plugin.ts

@@ -60,7 +60,7 @@ export interface ElasticsearchOptions {
 /**
  * @description
  * This plugin allows your product search to be powered by [Elasticsearch](https://github.com/elastic/elasticsearch) - a powerful Open Source search
- * engine.
+ * engine. This is a drop-in replacement for the {@link DefaultSearchPlugin}.
  *
  * ## Installation
  *

scripts/docs/generate-typescript-docs.ts

@@ -30,6 +30,10 @@ const sections: DocsSectionConfig[] = [
         sourceDirs: ['packages/admin-ui-plugin/src/'],
         outputPath: 'plugins',
     },
+    {
+        sourceDirs: ['packages/elasticsearch-plugin/src/'],
+        outputPath: 'plugins',
+    },
 ];
 
 generateTypescriptDocs(sections);