From 844e89d1c02ec139c087f47fe12e6bfc4a6eafd0 Mon Sep 17 00:00:00 2001 From: Dan Allen Date: Thu, 27 Dec 2018 13:16:44 -0700 Subject: update docs to reflect changes in Gulp build and Node requirements --- README.adoc | 43 +++++++++++----------- docs/modules/ROOT/pages/build-preview-ui.adoc | 27 +++++++------- docs/modules/ROOT/pages/index.adoc | 16 +++------ docs/modules/ROOT/pages/prerequisites.adoc | 51 ++++++++++++++------------- docs/modules/ROOT/pages/set-up-project.adoc | 10 +++--- 5 files changed, 67 insertions(+), 80 deletions(-) diff --git a/README.adoc b/README.adoc index ee2fe0b..b037252 100644 --- a/README.adoc +++ b/README.adoc @@ -47,7 +47,7 @@ A more comprehensive tutorial will be made available in the documentation. To preview and bundle the default UI, you need the following software on your computer: * {uri-git}[git] (command: `git`) -* {uri-node}[Node 8] (command: `node`) +* {uri-node}[Node] (command: `node`) * {uri-gulp}[Gulp CLI] (command: `gulp`) * {uri-yarn}[Yarn] (command: `yarn`) @@ -59,31 +59,31 @@ First, make sure you have git installed. If not, {uri-git-dl}[download and install] the git package for your system. -==== Node 8 +==== Node -Next, make sure that you have Node 8 installed. +Next, make sure that you have Node.js (herein "`Node`") installed. $ node --version If this command fails with an error, you don't have Node installed. -If the command doesn't report a Node 8 version (e.g., v8.9.4), you don't have a suitable version of Node installed. +If the command doesn't report a Node LTS version (e.g., v10.14.2), you don't have a suitable version of Node installed. While you can install Node from the official packages, we strongly recommend that you use {uri-nvm}[nvm] (Node Version Manager) to install and manage Node. Follow the {uri-nvm-install}[nvm installation instructions] to set up nvm on your machine. -Once you've installed nvm, open a new terminal and install Node 8 using the following command: +Once you've installed nvm, open a new terminal and install Node 10 using the following command: - $ nvm install 8 + $ nvm install 10 You can switch to this version of Node at any time using the following command: - $ nvm use 8 + $ nvm use 10 -To make Node 8 the default in new terminals, type: +To make Node 10 the default in new terminals, type: - $ nvm alias default 8 + $ nvm alias default 10 -Now that you have Node 8 installed, you can proceed with installing the Gulp CLI and Yarn. +Now that you have Node 10 installed, you can proceed with installing the Gulp CLI and Yarn. ==== Gulp CLI @@ -133,33 +133,30 @@ To build the UI and preview it in a local web server, run the `preview` command: $ gulp preview -You'll see two URLs listed in the output of this command: +You'll see a URL listed in the output of this command: .... -[BS] Access URLs: - ---------------------------------- - Local: http://localhost:5252 - External: http://192.168.1.7:5252 - ---------------------------------- -[BS] Serving files from: build -[BS] Watching files... +[12:59:28] Starting 'preview:serve'... +[12:59:28] Starting server... +[12:59:28] Server started http://localhost:5252 +[12:59:28] Running server .... -Navigate to the first URL to see the preview site. +Navigate to that URL to view the preview site. While this command is running, any changes you make to the source files will be instantly reflected in the browser. -This works by monitoring the project for changes, running the `build` task if a change is detected, and sending the updates to the browser. +This works by monitoring the project for changes, running the `preview:build` task if a change is detected, and sending the updates to the browser. Press kbd:[Ctrl+C] to stop the preview server and end the continuous build. === Package for Use with Antora -If you need to package the UI in order to preview the UI on the real site in local development, run the following command: +If you need to bundle the UI in order to preview the UI on the real site in local development, run the following command: - $ gulp pack + $ gulp bundle The UI bundle will be available at [.path]_build/ui-bundle.zip_. -You can then point Antora at this bundle using the `--ui-bundle` command-line option. +You can then point Antora at this bundle using the `--ui-bundle-url` command-line option. == Copyright and License diff --git a/docs/modules/ROOT/pages/build-preview-ui.adoc b/docs/modules/ROOT/pages/build-preview-ui.adoc index e386f05..3daab1c 100644 --- a/docs/modules/ROOT/pages/build-preview-ui.adoc +++ b/docs/modules/ROOT/pages/build-preview-ui.adoc @@ -26,45 +26,42 @@ The next two sections explain how to use these modes. To build the UI once for preview, then stop, execute the `build-preview` task using the following command: - $ gulp build:preview + $ gulp preview:build This task pre-compiles the UI files into the [.path]_public_ directory. To view the preview pages, navigate to the HTML pages in the [.path]_public_ directory using your browser (e.g., [.path]_public/index.html_). === Build Continuously -To avoid the need to run the `build-preview` task over and over, you can use the `preview` command instead to have it run continuously. +To avoid the need to run the `preview:build` task over and over, you can use the `preview` command instead to have it run continuously. This task also launches a local HTTP server so updates get synchronized with the browser (i.e., "`live reload`"). To launch the preview server, execute the following command: $ gulp preview -You'll see two URLs listed in the output of this command: +You'll see a URL listed in the output of this command: .... -[BS] Access URLs: - ---------------------------------- - Local: http://localhost:5252 - External: http://192.168.1.7:5252 - ---------------------------------- -[BS] Serving files from: build -[BS] Watching files... +[12:59:28] Starting 'preview:serve'... +[12:59:28] Starting server... +[12:59:28] Server started http://localhost:5252 +[12:59:28] Running server .... -Navigate to the first one to see the preview site. +Navigate to the URL to view the preview site. While this command is running, any changes you make to the source files will be instantly reflected in the browser. -This works by monitoring the project for changes, running the `build` task if a change is detected, and sending the updates to the browser. +This works by monitoring the project for changes, running the `preview:build` task if a change is detected, and sending the updates to the browser. Press kbd:[Ctrl+C] to stop the preview server and end the continuous build. == Package for Previewing -If you need to package the UI in order to preview the UI on the real site in local development, run the following command: +If you need to bundle the UI in order to preview the UI on the real site in local development, run the following command: - $ gulp pack + $ gulp bundle -The `pack` command also invokes the `lint` command to check that the CSS and JavaScript follow the coding standards. +The `bundle` command also invokes the `lint` command to check that the CSS and JavaScript follow the coding standards. The UI bundle will be available at [.path]_build/ui-bundle.zip_. You can then point Antora at this bundle using the `--ui-bundle-url` command-line option. diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index f4a227e..4258c3f 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/docs/modules/ROOT/pages/index.adoc @@ -49,7 +49,7 @@ Handlebars (file extension: `.hbs`):: Templates contain placeholders (i.e., mustache expressions like `+{{{page.title}}}+`) into which content is injected from a model. They also accommodate simple logic expressions for repeating content or including it conditionally (e.g., `+{{#each navigation}}+`) as well as partials (e.g., `+{{> header}}+`). -Gulp (script file: [.path]_gulpfile.js_):: +Gulp (script file: [.path]_gulpfile.js/index.js_):: {uri-gulp}[Gulp] is a build tool for JavaScript projects. It configures a collection of tasks that can be used to perform automated tasks such as compiling files, running a preview server, or publishing a release. @@ -91,7 +91,9 @@ Here's how the files are structured in the UI project: [.output] .... README.adoc -gulpfile.js +gulpfile.js/ + index.js + ... package.json yarn.lock src/ @@ -123,16 +125,6 @@ src/ preview-site-src/ index.html ui-model.yml -tasks/ - lib/ - gulp-prettier-eslint.js - build.js - build-preview.js - format.js - lint-css.js - lint-js.js - pack.js - preview.js .... A Gulp build is used to compile and assemble the UI project files into a UI bundle. diff --git a/docs/modules/ROOT/pages/prerequisites.adoc b/docs/modules/ROOT/pages/prerequisites.adoc index 28a0f7b..a4f4df2 100644 --- a/docs/modules/ROOT/pages/prerequisites.adoc +++ b/docs/modules/ROOT/pages/prerequisites.adoc @@ -6,23 +6,23 @@ endif::[] :idprefix: :idseparator: - // URIs: -:uri-nvm: https://github.com/creationix/nvm -:uri-node: https://nodejs.org -:uri-gulp: http://gulpjs.com -:uri-yarn: https://yarnpkg.com -:uri-git: https://git-scm.com -:uri-git-dl: {uri-git}/downloads -:uri-nvm-install: {uri-nvm}#installation +:url-nvm: https://github.com/creationix/nvm +:url-node: https://nodejs.org +:url-gulp: http://gulpjs.com +:url-yarn: https://yarnpkg.com +:url-git: https://git-scm.com +:url-git-dl: {url-git}/downloads +:url-node-releases: https://nodejs.org/en/about/releases/ // These prerequisite instructions are less detailed than Antora's prerequisite instructions, I don't know if this is a concern or not. An Antora UI project is based on tools built atop Node.js (aka Node), namely: -* {uri-node}[Node] (command: `node`) - ** {uri-nvm}[nvm] (optional, but strongly recommended) -* {uri-gulp}[Gulp] (command: `gulp`) -* {uri-yarn}[Yarn] (command: `yarn`) +* {url-node}[Node] (command: `node`) + ** {url-nvm}[nvm] (optional, but strongly recommended) +* {url-gulp}[Gulp] (command: `gulp`) +* {url-yarn}[Yarn] (command: `yarn`) -You also need {uri-git}[git] (command: `git`) to pull down the project and push updates to it. +You also need {url-git}[git] (command: `git`) to pull down the project and push updates to it. == git @@ -30,27 +30,28 @@ First, make sure you have git installed. $ git --version -If not, {uri-git-dl}[download and install] the git package for your system. +If not, {url-git-dl}[download and install] the git package for your system. -== Node 8 +== Node -Next, make sure that you have Node 8 installed. -While you can install Node from the official packages, we strongly recommend that you use {uri-nvm}[nvm] (Node Version Manager) to install and manage Node. -Follow the {uri-nvm-install}[nvm installation instructions] to set up nvm on your machine. +You need Node installed on your machine to use Antora, including the default UI. +Antora follows Node's release schedule, so we advise that you choose an active long term support (LTS) release of Node. +We recommend using the latest active Node LTS version. +While you can use other versions of Node, Antora is only tested against LTS releases. -Once you've installed nvm, open a new terminal and install Node 8 using the following command: +To check whether you have Node installed, and which version, open a terminal and type: - $ nvm install 8 + $ node --version -You can switch to this version of Node at any time using the following command: +You should see a version string, such as: - $ nvm use 8 + v10.14.2 -To make Node 8 the default in new terminals, type: +If the command fails with an error, it means you don't have Node installed. +The best way to install Node is to use nvm (Node Version Manager). +Refer to xref:antora:install:linux-requirements.adoc#install-nvm[Install nvm and Node (Linux)], xref:antora:install:macos-requirements.adoc#install-nvm[Install nvm and Node (macOS)], or xref:antora:install:windows-requirements.adoc#install-nvm[Install nvm and Node (Windows)] for instructions. - $ nvm alias default 8 - -Now that you have Node 8 installed, you can proceed with installing the Gulp CLI and Yarn. +Once you have Node installed, you can proceed with installing Gulp's CLI and Yarn. == Gulp CLI diff --git a/docs/modules/ROOT/pages/set-up-project.adoc b/docs/modules/ROOT/pages/set-up-project.adoc index b413de6..31dfd73 100644 --- a/docs/modules/ROOT/pages/set-up-project.adoc +++ b/docs/modules/ROOT/pages/set-up-project.adoc @@ -53,15 +53,15 @@ You should see: [.output] .... -lint:css -lint:js +default +clean lint format build -build:preview +bundle +bundle:pack preview -pack -default +preview:build .... We'll explain what each of these tasks are for and when to use them. -- cgit v1.2.3