chore: Update docs readme

docs/README.md

@@ -1,37 +1,46 @@
 # Vendure Docs
 
-This is the source for the Vendure documentation website. Docs are written in markdown and the website is generated with [Hugo](https://gohugo.io).
+This is the source for the documentation part of the Vendure. Docs are written in markdown and the website is generated with [Hugo](https://gohugo.io).
 
-## Building the docs
+## Structure
 
-1. [Install Hugo](https://gohugo.io/getting-started/installing/) on your machine. Currently, the live docs are built with **Hugo v0.7**.
-2. Install docs dependencies by running `yarn install` or `npm install` in this directory.
-3. Then run the `docs:build` script from the root of this repo.
+```
+docs
+├── content/
+│   └── # The actual markdown files
+│       # which make up the docs, both manually-written
+│       # and auto-generated from source.
+├── data/
+│   └── # Data files used in generating the docs website
+└── diagrams/
+    └── # PlantUML diagrams used in the documentation
+```
 
-This task will:
+The `content` directory contains the actual documentation markdown files and images.
 
-* Auto-generate the API markdown files based on the Vendure server source (see below)
-* Run webpack to build the JavaScript and CSS for the docs site
-* Run Hugo to build and output the site into the `docs/public` directory.
+## Docs Generation
 
-## Dev mode
+All of the documentation for the TypeScript APIs and the GraphQL API is auto-generated.
 
-Run `docs:watch` when developing the docs site. This will run all of the above in watch mode, so you can go to [http://localhost:1313](http://localhost:1313) to view the docs site. It will auto-reload the browser on any changes to the server source, the docs script/styles assets, or the Hugo templates.
+Run the `docs:build` script from the root of this repo.
 
-## Docs Generation
+This task will:
+
+* Auto-generate the API markdown files based on the Vendure server source (see below)
+* Update the build data to match the current version and commit
 
-All of the documentation for the interal APIs (configuration docs) and the GraphQL API is auto-generated.
+The generated markdown is then used by an external project which builds the Vendure website.
 
 ### GraphQL Docs
 
-The GraphQL API docs are generated from the `schema.json` file which is created as part of the "generate-gql-types" script.
+The GraphQL API docs are generated from the `schema.json` file which is created as part of the `codegen` script.
 
-### Configuration Docs
+### TypeScript Docs
 
-The configuration docs are generated from the TypeScript source files by running the "generate-config-docs" script:
+The TypeScript docs are generated from the TypeScript source files by running the `docs:generate-typescript-docs` script:
 
 ```bash
-yarn generate-config-docs [-w]
+yarn docs:generate-typescript-docs [-w]
 ```
 
 This script uses the TypeScript compiler API to traverse the server source code and extract data about the types as well as other information such as descriptions and default values.
@@ -60,7 +69,12 @@ This tag specifies the text description of the declaration. It supports markdown
 
 ##### `@example`
 
-This tag should be used to include any code blocks. Remember to specify the language after the opening delimiter for correct highlighting. Also applies to class/interface members.
+This tag should be used to include any code blocks. Remember to specify the language after the opening delimiter for correct highlighting. Also applies to class/interface members. If the example code includes the `@` character, it must be escaped
+so that it is not interpreted as a JSDoc tag:
+
+```ts
+import { VendureConfig } from '\@vendure/core';
+```
 
 ##### `@default`
 
@@ -68,7 +82,7 @@ This is used to specify the default value of a property, e.g. when documenting a
 
 ##### `@internal`
 
-This is used to exlude members from appearing in the docs. For example, a class may need a particular
+This is used to exclude members from appearing in the docs. For example, a class may need a particular
 public method for internal use, but this method is not intended to be used by external consumers of that
 class.
 
@@ -108,12 +122,3 @@ export class Greeter {
     }
 }
 ````
-
-
-## A note on icons
-
-The docs site also uses the [Clarity icons](https://clarity.design/icons) to maintain consistency with the Vendure admin ui app. However, currently [this bug](https://github.com/vmware/clarity/issues/2599) makes the use of the custom-elements based icons unfeasible since it adds about 400kb to the JS bundle size. This is unacceptable for what is essentially a static HTML site.
-
-So for now we are hand-picking the icons as svg files from [https://icongr.am/clarity](https://icongr.am/clarity) and using them as regular images. The downside is that to get different colours, the svg files themselves must be edited.
-
-This is a pain but for the small number of icons planned, it is workable.

docs/build.js

@@ -1,41 +0,0 @@
-/* tslint:disable:no-console */
-const fs = require('fs');
-const { exec } = require('child_process');
-
-getLastCommitHash()
-    .then(hash => writeBuildInfo(hash))
-    .then(() => {
-        console.log('Updated build info');
-        process.exit(0);
-    })
-    .catch(err => {
-        console.error(err);
-        process.exit(1);
-    });
-
-function writeBuildInfo(commitHash) {
-    const corePackageJson = require('../packages/core/package');
-    const content = {
-        version: corePackageJson.version,
-        commit: commitHash,
-    };
-    return new Promise((resolve, reject) => {
-        fs.writeFile('./data/build.json', JSON.stringify(content, null, 2), err => {
-            if (err) {
-                reject(err);
-            }
-            resolve();
-        });
-    });
-}
-
-function getLastCommitHash() {
-    return new Promise((resolve, reject) => {
-        exec(`git log --pretty=format:'%h' -n 1`, (err, out) => {
-            if (err) {
-                reject(err);
-            }
-            resolve(out.replace(/'/g, ''));
-        });
-    });
-}

docs/data/build.json

@@ -1,4 +1,4 @@
 {
-  "version": "0.18.5",
-  "commit": "2073e7cb"
-}
+  "version": "1.0.0-beta.7",
+  "commit": "469f577a"
+}