Merge pull request #90 from tigergraph/TCE-6160

TCE-6160 feat(docs): Support Cloud Docs Preview and local build;

Author: pengchengrun

README.adoc

@@ -6,4 +6,56 @@ This repository only contains the source files for the published documentation.
 To view the published version, see link:https://docs.tigergraph.com/cloud[TigerGraph Cloud Documentation].
 
 == Contribution
-For instructions on how to contribute to this repository, see link:https://github.com/tigergraph/doc-site/blob/main/contribution.adoc[Contribution guidelines].
+For instructions on how to contribute to this repository, see link:https://github.com/tigergraph/doc-site/blob/main/contribution.adoc[Contribution guidelines].
+
+== Install dependencies
+To install dependencies, navigate to this repository and run:
+[,console]
+----
+npm install
+----
+
+== Build site locally
+To build the site locally, run:
+[,console]
+----
+npm run build
+----
+The build will be available in the `build/` folder in the root directory. 
+
+IMPORTANT: Though the files are all in the `/build` folder, you won't be able to access other pages through the links if the files are not served by a server.
+To preview locally, you can <<Run a local server to view the build>>. If you really don't want to use a local server, edit the `antora-playbook.yml` file in your local environment, and change the `html_extension_style` under `urls` to `default`. This allows you to open the static files and have the links work.  
+
+=== Build from your local content source repository
+To have Antora build the site from your local content source repository, change the corresponding content source in the file `antora-playbook.yml` to point to your local git repository. 
+
+See https://docs.antora.org/antora/2.3/playbook/content-source-url/#local-urls[Use local content repositories] on Antora's documentation. 
+
+== Watch Mode
+
+Watch Mode launches a local web server for preview. It will continue watching your local content source repository changes and rebuild the site.
+
+[,console]
+----
+npm run dev
+----
+
+You can access the web server at http://localhost:5000[http://localhost:5000].
+
+== Run a local server to view the build
+
+To open the build, run:
+[,console]
+----
+$ npm i -g http-server
+$ http-server build/site -c-1
+----
+Upon launching the command, the local address of the web server will be displayed in your terminal. You should see the following output in your terminal:
+
+----
+Starting up http-server, serving build/site
+Available on:
+  http://127.0.0.1:8080
+  http://192.168.1.8:8080
+Hit CTRL-C to stop the server
+----

antora-playbook.yml

@@ -0,0 +1,17 @@
+site:
+  title: "Cloud Doc Test"
+  start_page: "cloud4:overview:index.adoc"
+
+content:
+  sources:
+    - url: .
+      branches: HEAD
+      start_paths: [modules/cloud4, modules/cloud]
+
+output:
+  dir: ./build/site
+
+ui:
+  bundle:
+    url: https://github.com/tigergraph/antora-ui/blob/main/build/ui-bundle.zip?raw=true
+    snapshot: true

gulpfile.js

@@ -0,0 +1,38 @@
+'use strict'
+
+const connect = require('gulp-connect')
+const fs = require('fs')
+const generator = require('@antora/site-generator-default')
+const { reload: livereload } = process.env.LIVERELOAD === 'true' ? require('gulp-connect') : {}
+const { series, src, watch } = require('gulp')
+const yaml = require('js-yaml')
+
+const playbookFilename = 'antora-playbook.yml'
+const playbook = yaml.load(fs.readFileSync(playbookFilename, 'utf8'))
+const outputDir = (playbook.output || {}).dir || './build/site'
+const serverConfig = { name: 'Preview Site', livereload, port: 5000, root: outputDir }
+const antoraArgs = ['--playbook', playbookFilename]
+const watchPatterns = playbook.content.sources.filter((source) => !source.url.includes(':')).reduce((accum, source) => {
+  accum.push(`${source.url}/${source.start_path ? source.start_path + '/' : ''}antora.yml`)
+  accum.push(`${source.url}/${source.start_path ? source.start_path + '/' : ''}**/*.adoc`)
+  return accum
+}, [])
+
+function generate (done) {
+  generator(antoraArgs, process.env)
+    .then(() => done())
+    .catch((err) => {
+      console.log(err)
+      done()
+    })
+}
+
+function serve (done) {
+  connect.server(serverConfig, function () {
+    this.server.on('close', done)
+    watch(watchPatterns, generate)
+    if (livereload) watch(this.root).on('change', (filepath) => src(filepath, { read: false }).pipe(livereload()))
+  })
+}
+
+module.exports = { serve, generate, default: series(generate, serve) }

package.json

@@ -0,0 +1,21 @@
+{
+  "name": "cloud-docs",
+  "version": "1.0.0",
+  "description": "",
+  "main": "index.js",
+  "scripts": {
+    "build": "antora generate --fetch antora-playbook.yml",
+    "dev": "gulp",
+    "serve": "http-server build/site -c-1"
+  },
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "@antora/cli": "^3.1.1",
+    "@antora/site-generator-default": "^3.1.1",
+    "gulp": "^4.0.2",
+    "gulp-cli": "^2.3.0",
+    "gulp-connect": "^5.7.0",
+    "js-yaml": "^4.1.0"
+  }
+}