Merge pull request #108 from alanconway/readme-dev

Readme dev

Author: kameshsampath

README-DEV.adoc

@@ -0,0 +1,43 @@
+Modifying the tutorial
+======================
+
+The tutorial is written in asciidoc and can be updated using any text editor.
+You can preview changes as you make them as follows:
+
+1. Install the `antora` website generator and `gulp` build system
++
+....
+npm install -g @antora/cli @antora/site-generator-default gulp gulp-connect gulp-open yaml-js
+....
+
+2. Create a `dev-site.yml` file (the `site.yml` file is for the public website)
++
+.dev-site.yml
+....
+runtime:
+  cache_dir: ./.cache/antora
+
+site:
+  title: Knative Tutorial
+  url: https://redhat-developer-demos.github.io/knative-tutorial
+  start_page: knative-tutorial::index.adoc
+
+content:
+  sources:
+    - url: .
+      branches: HEAD
+      start_path: documentation
+
+ui:
+  bundle:
+    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/master/raw/build/ui-bundle.zip?job=bundle-stable
+    snapshot: true
+  supplemental_files: ./supplemental-ui
+
+output:
+  dir: ./gh-pages
+....
+
+3. Run `node_modules/.bin/gulp`
+
+This will generate HTML, start a local web server at `localhost:5373`, open the server index in a browser, and automatically update the HTML when the asciidoc source changes.

gulpfile.js

@@ -4,12 +4,13 @@ const connect = require("gulp-connect");
 const fs = require("fs");
 const generator = require("@antora/site-generator-default");
 const gulp = require("gulp");
+const open = require("gulp-open");
 const yaml = require("yaml-js");
 
 let filename = "dev-site.yml";
 let args = ["--playbook", filename];
 
-gulp.task("build", function(cb) {
+function build(cb) {
   /**
    * Use the '@antora/site-generator-default' node module to build.
    * It's analogous to `$ antora --playbook local-antora-playbook.yml`.
@@ -19,44 +20,36 @@ gulp.task("build", function(cb) {
    * a separate process for each run. So if a build error occurs with the `gulp`
    * command it can be useful to check if it also happens with the CLI command.
    */
-  generator(args, process.env)
-    .then(() => {
-      cb();
-    })
-    .catch(err => {
-      console.log(err);
-      cb();
-    });
-});
+  generator(args, process.env).catch(err => { console.log(err); })
+  connect.reload()
+  cb();
+}
 
-gulp.task("preview", ["build"], function() {
-  /**
-   * Remove the line gulp.src('README.adoc')
-   * This is placeholder code to follow the gulp-connect
-   * example. Could not make it work any other way.
-   */
-  gulp.src("README.adoc").pipe(connect.reload());
-});
-
-gulp.task("watch", function() {
+function watch() {
   let json_content = fs.readFileSync(`${__dirname}/${filename}`, "UTF-8");
   let yaml_content = yaml.load(json_content);
-  let dirs = yaml_content.content.sources.map(source => [
-    `${source.url}/**/**.yml`,
-    `${source.url}/**/**.adoc`,
+  let sources = yaml_content.content.sources.map(source => [
+    `${source.url}/**/*.yml`,
+    `${source.url}/**/*.adoc`,
     `${source.url}/**/**.hbs`
   ]);
-  dirs.push(["dev-site.yml"]);
-  gulp.watch(dirs, ["preview"]);
-});
+  sources.push(["dev-site.yml"]);
+  sources = [].concat.apply([], sources) // Flatten the array
+  gulp.watch(sources, build)
+}
 
-gulp.task("connect", function() {
+function serve() {
   connect.server({
     port: 5353,
     name: "Dev Server",
     livereload: true,
     root: "gh-pages"
   });
-});
+}
+
+function browse() {
+  gulp.src("gh-pages/index.html").pipe(open({uri: 'http://localhost:5353'}))
+}
 
-gulp.task("default", ["connect", "watch", "build"]);
+exports.build = build;
+exports.default = gulp.parallel(serve, watch, browse)