java
/
jMonkeyEngine-wiki
cermin dari https://github.com/jMonkeyEngine/wiki.git


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377
							<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width,initial-scale=1">
    <title>Converting the Wiki to Antora :: jMonkeyEngine Docs</title>
    <link rel="canonical" href="https://wiki.jmonkeyengine.org/docs/transition-docs/antora_setup.html">
    <meta name="generator" content="Antora 2.3.3">
    <link rel="stylesheet" href="../../_/css/site.css">
  </head>
  <body class="article">
<header class="header">
  <nav class="navbar">
    <div class="navbar-brand">
      <a class="navbar-item" href="https://wiki.jmonkeyengine.org">jMonkeyEngine Docs</a>
      <button class="navbar-burger" data-target="topbar-nav">
        <span></span>
        <span></span>
        <span></span>
      </button>
    </div>
    <div id="topbar-nav" class="navbar-menu">
      <div class="navbar-end">
        <a class="navbar-item" href="#">Home</a>
        <div class="navbar-item has-dropdown is-hoverable">
          <a class="navbar-link" href="#">Products</a>
          <div class="navbar-dropdown">
            <a class="navbar-item" href="#">Product A</a>
            <a class="navbar-item" href="#">Product B</a>
            <a class="navbar-item" href="#">Product C</a>
          </div>
        </div>
        <div class="navbar-item has-dropdown is-hoverable">
          <a class="navbar-link" href="#">Services</a>
          <div class="navbar-dropdown">
            <a class="navbar-item" href="#">Service A</a>
            <a class="navbar-item" href="#">Service B</a>
            <a class="navbar-item" href="#">Service C</a>
          </div>
        </div>
        <div class="navbar-item has-dropdown is-hoverable">
          <a class="navbar-link" href="#">Resources</a>
          <div class="navbar-dropdown">
            <a class="navbar-item" href="#">Resource A</a>
            <a class="navbar-item" href="#">Resource B</a>
            <a class="navbar-item" href="#">Resource C</a>
          </div>
        </div>
        <div class="navbar-item">
          <span class="control">
            <a class="button is-primary" href="#">Download</a>
          </span>
        </div>
      </div>
    </div>
  </nav>
</header>
<div class="body">
<div class="nav-container" data-component="docs" data-version="master">
  <aside class="nav">
    <div class="panels">
<div class="nav-panel-menu is-active" data-panel="menu">
  <nav class="nav-menu">
    <h3 class="title"><a href="../jme3.html">Docs</a></h3>
<ul class="nav-list">
  <li class="nav-item" data-depth="0">
<ul class="nav-list">
  <li class="nav-item" data-depth="1">
    <a class="nav-link" href="../documentation.html">Getting Started</a>
  </li>
  <li class="nav-item" data-depth="1">
    <a class="nav-link" href="https://javadoc.jmonkeyengine.org/v3.3.2-stable">JavaDoc</a>
  </li>
  <li class="nav-item" data-depth="1">
    <button class="nav-item-toggle"></button>
    <a class="nav-link" href="../jme3.html">jMonkeyEngine 3</a>
<ul class="nav-list">
  <li class="nav-item" data-depth="2">
    <button class="nav-item-toggle"></button>
    <span class="nav-text">Beginner Tutorials</span>
<ul class="nav-list">
  <li class="nav-item" data-depth="3">
    <a class="nav-link" href="../jme3/beginner/hello_simpleapplication.html">Hello SimpleApplication</a>
  </li>
  <li class="nav-item" data-depth="3">
    <a class="nav-link" href="../jme3/beginner/hello_node.html">Hello Node</a>
  </li>
  <li class="nav-item" data-depth="3">
    <a class="nav-link" href="../jme3/beginner/hello_asset.html">Hello Asset</a>
  </li>
  <li class="nav-item" data-depth="3">
    <a class="nav-link" href="../jme3/beginner/hello_main_event_loop.html">Hello Main Event Loop</a>
  </li>
  <li class="nav-item" data-depth="3">
    <a class="nav-link" href="../jme3/beginner/hello_input_system.html">Hello Input System</a>
  </li>
  <li class="nav-item" data-depth="3">
    <a class="nav-link" href="../jme3/beginner/hello_material.html">Hello Material</a>
  </li>
  <li class="nav-item" data-depth="3">
    <a class="nav-link" href="../jme3/beginner/hello_animation.html">Hello Animation</a>
  </li>
  <li class="nav-item" data-depth="3">
    <a class="nav-link" href="../jme3/beginner/hello_picking.html">Hello Picking</a>
  </li>
  <li class="nav-item" data-depth="3">
    <a class="nav-link" href="../jme3/beginner/hello_collision.html">Hello Collision</a>
  </li>
  <li class="nav-item" data-depth="3">
    <a class="nav-link" href="../jme3/beginner/hello_terrain.html">Hello Terrain</a>
  </li>
  <li class="nav-item" data-depth="3">
    <a class="nav-link" href="../jme3/beginner/hello_audio.html">Hello Audio</a>
  </li>
  <li class="nav-item" data-depth="3">
    <a class="nav-link" href="../jme3/beginner/hello_effects.html">Hello Effects</a>
  </li>
  <li class="nav-item" data-depth="3">
    <a class="nav-link" href="../jme3/beginner/hello_physics.html">Hello Physics</a>
  </li>
</ul>
  </li>
  <li class="nav-item" data-depth="2">
    <button class="nav-item-toggle"></button>
    <span class="nav-text">Intermediate Tutorials</span>
<ul class="nav-list">
  <li class="nav-item" data-depth="3">
    <button class="nav-item-toggle"></button>
    <span class="nav-text">Concepts</span>
<ul class="nav-list">
  <li class="nav-item" data-depth="4">
    <a class="nav-link" href="../jme3/intermediate/best_practices.html">Best Practices</a>
  </li>
  <li class="nav-item" data-depth="4">
    <a class="nav-link" href="../jme3/intermediate/simpleapplication.html">Simple Application</a>
  </li>
  <li class="nav-item" data-depth="4">
    <a class="nav-link" href="../jme3/features.html">Features</a>
  </li>
  <li class="nav-item" data-depth="4">
    <a class="nav-link" href="../jme3/intermediate/optimization.html">Optimization</a>
  </li>
  <li class="nav-item" data-depth="4">
    <a class="nav-link" href="../jme3/faq.html">FAQ</a>
  </li>
</ul>
  </li>
  <li class="nav-item" data-depth="3">
    <button class="nav-item-toggle"></button>
    <span class="nav-text">Math Concepts</span>
<ul class="nav-list">
  <li class="nav-item" data-depth="4">
    <a class="nav-link" href="../jme3/math_for_dummies.html">Math For Dummies</a>
  </li>
  <li class="nav-item" data-depth="4">
    <a class="nav-link" href="../jme3/intermediate/math.html">Math</a>
  </li>
  <li class="nav-item" data-depth="4">
    <a class="nav-link" href="../jme3/math.html">More Math</a>
  </li>
  <li class="nav-item" data-depth="4">
    <a class="nav-link" href="../jme3/rotate.html">Rotate</a>
  </li>
  <li class="nav-item" data-depth="4">
    <a class="nav-link" href="../jme3/math_video_tutorials.html">Math Video Tutorials</a>
  </li>
</ul>
  </li>
  <li class="nav-item" data-depth="3">
    <button class="nav-item-toggle"></button>
    <span class="nav-text">3D Graphics Concepts</span>
<ul class="nav-list">
  <li class="nav-item" data-depth="4">
    <a class="nav-link" href="../jme3/intermediate/multi-media_asset_pipeline.html">Multi-Media Asset Pipeline</a>
  </li>
  <li class="nav-item" data-depth="4">
    <a class="nav-link" href="../jme3/scenegraph_for_dummies.html">Scenegraph for Dummies</a>
  </li>
  <li class="nav-item" data-depth="4">
    <a class="nav-link" href="../jme3/beginner/hellovector.html">Hello Vector</a>
  </li>
  <li class="nav-item" data-depth="4">
    <a class="nav-link" href="../jme3/terminology.html">Terminology</a>
  </li>
  <li class="nav-item" data-depth="4">
    <a class="nav-link" href="../jme3/intermediate/how_to_use_materials.html">How to Use Materials</a>
  </li>
  <li class="nav-item" data-depth="4">
    <a class="nav-link" href="../jme3/intermediate/transparency_sorting.html">Transparency and Sorting</a>
  </li>
  <li class="nav-item" data-depth="4">
    <a class="nav-link" href="../jme3/external/blender.html">Importing from Blender</a>
  </li>
  <li class="nav-item" data-depth="4">
    <a class="nav-link" href="../jme3/external/3dsmax.html">Importing from 3DS Max</a>
  </li>
</ul>
  </li>
</ul>
  </li>
</ul>
  </li>
  <li class="nav-item" data-depth="1">
    <a class="nav-link" href="../logo.html">Logo Usage</a>
  </li>
  <li class="nav-item" data-depth="1">
    <a class="nav-link" href="../bsd_license.html">License</a>
  </li>
  <li class="nav-item" data-depth="1">
    <a class="nav-link" href="../github_tips.html">Github Tips</a>
  </li>
</ul>
  </li>
  <li class="nav-item" data-depth="0">
    <button class="nav-item-toggle"></button>
    <span class="nav-text">SDK</span>
<ul class="nav-list">
  <li class="nav-item" data-depth="1">
    <a class="nav-link" href="../sdk.html">jMonkeyEngine SDK</a>
  </li>
</ul>
  </li>
</ul>
  </nav>
</div>
<div class="nav-panel-explore" data-panel="explore">
  <div class="context">
    <span class="title">Docs</span>
    <span class="version">master</span>
  </div>
  <ul class="components">
    <li class="component is-current">
      <span class="title">Docs</span>
      <ul class="versions">
        <li class="version is-current is-latest">
          <a href="../jme3.html">master</a>
        </li>
      </ul>
    </li>
    <li class="component">
      <span class="title">Wiki UI</span>
      <ul class="versions">
        <li class="version is-latest">
          <a href="../../wiki-ui/index.html">master</a>
        </li>
      </ul>
    </li>
  </ul>
</div>
    </div>
  </aside>
</div>
<main class="article">
<div class="toolbar" role="navigation">
<button class="nav-toggle"></button>
  <a href="../documentation.html" class="home-link"></a>
<nav class="breadcrumbs" aria-label="breadcrumbs">
  <ul>
    <li><a href="../jme3.html">Docs</a></li>
    <li><a href="antora_setup.html">Converting the Wiki to Antora</a></li>
  </ul>
</nav>
  <div class="edit-this-page"><a href="https://github.com/jMonkeyEngine/wiki/edit/master/docs/modules/transition-docs/pages/antora_setup.adoc">Edit this Page</a></div>
  </div>
  <div class="content">
<article class="doc">
<h1 class="page">Converting the Wiki to Antora</h1>
<div class="sect1">
<h2 id="getting-started"><a class="anchor" href="#getting-started"></a>Getting Started</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Setup is based off <a href="https://help.github.com/en/actions/language-and-framework-guides/using-nodejs-with-github-actions">Using Node.js with GitHub Actions</a>, <a href="https://help.github.com/en/actions/configuring-and-managing-workflows/caching-dependencies-to-speed-up-workflows">Caching dependencies to speed up workflows</a>, and the <a href="https://docs.antora.org/antora/2.3/install/install-antora/">Install Antora</a> guides. It is expected that the repository has already been cloned locally.</p>
</div>
<div class="olist arabic">
<div class="title">Definitions</div>
<ol class="arabic">
<li>
<p>GitHub Web Interface (GWI)</p>
</li>
<li>
<p>Git Command Line Interface (CLI)</p>
</li>
<li>
<p>Continuous Integration (CI)</p>
</li>
</ol>
</div>
<div class="olist arabic">
<div class="title">Tools needed</div>
<ol class="arabic">
<li>
<p>A gitHub account.</p>
</li>
<li>
<p>The Atom Editor, setup for using AsciiDoctor.</p>
</li>
<li>
<p>Git (CLI).</p>
</li>
</ol>
</div>
</div>
</div>
<div class="sect1">
<h2 id="activating-dispatch-event"><a class="anchor" href="#activating-dispatch-event"></a>Activating Dispatch Event</h2>
<div class="sectionbody">
<div class="paragraph">
<p>We use a dispatch_event to build the wiki anytime there are new changes tagged on the wiki-ui repository.</p>
</div>
<div class="paragraph">
<p>To activate the <code>Docs Dispatch Event</code> command, it must share a personal access token, with permissions <code>public_repo</code>, with the jMonkeyEngine Wiki.</p>
</div>
<div class="paragraph">
<p>You setup the token first from your personal account with the token name <code>WIKI_UI_DISPATCH</code>.</p>
</div>
<div class="paragraph">
<p>See: <a href="https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line" class="bare">https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line</a></p>
</div>
<div class="paragraph">
<p>Then in the wiki-ui repository under <span class="menuseq"><b class="menu">Settings</b>&#160;<i class="fa fa-angle-right caret"></i> <b class="menuitem">Secrets</b></span> add the new token with the format:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>username:token</code></pre>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="setup-of-node-js"><a class="anchor" href="#setup-of-node-js"></a>Setup of Node.js</h2>
<div class="sectionbody">
<div class="paragraph">
<p>GitHub Actions requires a workflow file (main.yml) to be located in a <code>.github/workflows</code> folder. In order to use (CI) with the workflow, there must be a <code>package.json</code> and <code>package-lock.json</code> file located in the root of the repository. Node.js will build and update these files for us.</p>
</div>
<div class="ulist">
<ul>
<li>
<p>We use an action named &#8220;EndBug/add-and-commit@v4&#8221; to commit the <code>package.json</code> and <code>package-lock.json</code> files to the repository any time there are changes that affect these files.</p>
</li>
<li>
<p>We use an action named &#8220;peaceiris/actions-gh-pages@v3&#8221; to publish the built website to the <code>gh-pages</code> branch whenever there is a push to the repo.</p>
</li>
<li>
<p>We use a <code>repository_dispatch</code> webhook event configured to recieve events from the wiki-ui repo to build the docs whenever there is a new release pushed to the UI repository.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>These steps are all built into the workflow file.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
<div class="paragraph">
<p>You can edit/add the main.yml from a git (CLI) or the (GWI) only.</p>
</div>
<div class="paragraph">
<p>This tutorial uses (CLI) for workflow file edits, and the Atom Editor for editing all other files. Since both the (CLI) and Atom Editor are working with the same repository, both will stay synchronized with the local repository.</p>
</div>
</td>
</tr>
</table>
</div>
</div>
</div>
<div class="sect1">
<h2 id="prepare-repository"><a class="anchor" href="#prepare-repository"></a>Prepare Repository</h2>
<div class="sectionbody">
<div class="olist arabic">
<ol class="arabic">
<li>
<p>From the (CLI):</p>
<div class="olist loweralpha">
<ol class="loweralpha" type="a">
<li>
<p>Checkout a new branch named <code>antora-setup</code>.</p>
</li>
<li>
<p>Create the destination folder <code>docs/modules/ROOT</code> in the root of the local repository.</p>
</li>
<li>
<p>Move the folders found inside the Wiki <code>src/docs/</code> folder to the destination folder.</p>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>This will be the destination final results.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>|-docs
   |-modules
      |-ROOT
         |-images
         |-pages
         |-resources</code></pre>
</div>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
<div class="paragraph">
<p>Use <code>git mv</code> from the (CLI) to retain all history.</p>
</div>
<div class="paragraph">
<p>git mv [-v] [-n] &lt;source&gt; &lt;destination&gt;</p>
</div>
<div class="paragraph">
<p>* [-n] option will do nothing; only show what would happen. Remove when ready to complete the move.</p>
</div>
</td>
</tr>
</table>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>&lt;source&gt;</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>&lt;destination&gt;</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>src/docs/images</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>docs/modules/ROOT/images</code></p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>src/docs/resources</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>docs/modules/ROOT/resources</code></p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>src/docs/asciidocs</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>docs/modules/ROOT/pages</code></p>
</div></div></td>
</tr>
</tbody>
</table>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
The move to the <code>docs/modules/ROOT/pages</code> folder is a rename of the <code>asciidoc</code> folder. Do not move the folder into pages.
</td>
</tr>
</table>
</div>
</div>
</div>
</li>
<li>
<p>Add, commit and push the <code>antora-setup</code> branch to the repository.</p>
</li>
</ol>
</div>
</li>
</ol>
</div>
</div>
</div>
<div class="sect1">
<h2 id="setup-workflow"><a class="anchor" href="#setup-workflow"></a>Setup Workflow</h2>
<div class="sectionbody">
<div class="paragraph">
<p>All files for setup can be found inside the <code>transition-docs</code> module where this document is located.  These are the final configuration files using the <code>master</code> branch to trigger builds and assume all steps have been completed and Antora is now in control of the build process for the wiki.</p>
</div>
<div class="paragraph">
<p>Using the workflow shown below will execute on the <code>antora-setup</code> branch pushing the build to the <code>gh-pages</code> branch allowing setup to be completed. This will allow for testing the build prior to merging the branch to <code>master</code>.</p>
</div>
<div class="paragraph">
<p>The changes that affect the workflow branch are as follows:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>on:
  push:
    branches: [ antora-setup ]

    uses: actions/checkout@v2
    with:
      ref: antora-setup</code></pre>
</div>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
It&#8217;s a good idea to have the (GWI) actions tab open in a browser so the build can be monitored.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>The action <code>EndBug/add-and-commit@v4</code> will commit to the branch that triggered the workflow.</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>From the (CLI):</p>
<div class="olist loweralpha">
<ol class="loweralpha" type="a">
<li>
<p>Create a <code>.github/workflows</code> folder in the <code>antora-setup</code> branch.</p>
</li>
<li>
<p>Add the initial &#8220;main.yml&#8221; file below as a new workflow.</p>
<div class="openblock">
<div class="content">
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
The initial file is designed to be used in steps, commenting and uncommenting commands as the changeover progresses. The finalized <a href="_attachments/main.yml">main.yml</a> is in the <code>transition-docs</code> module.
</td>
</tr>
</table>
</div>
<div class="listingblock">
<div class="title">Initial main.yml</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-yml hljs" data-lang="yml"># This file can be used to configure the Node.js build for Antora ci without
# having Node installed locally. See 'transition-docs/antora_setup.adoc' in the root
# of this repo for details of how to use this file.
#
# The action add-and-commit will always commit the package-lock.json,
# package.json and Antora cache only if changes are made to the files.
#
# If the package-lock.json or package.json files are updated or new depends are
# installed, the 'npm ci' should be always ran thereafter to speed up build
# times. When ci is active, the package-lock.json and package.json files in root
# will not be updated.
#
# Uses the action actions-gh-page to publish pages to the gh-pages branch,
# including a required .nojekyll file that Antora requires for configuration.
#
# The 'actions/cache@v2' creates a new cache when the packages in
# package-lock.json file change, or when the workflow runner's operating system
# changes.

name: Build Docs

on:
  push:
    branches: [ antora-setup ]
  # Initiate a build to pull in the wiki-ui repository changes.
  repository_dispatch:
    types: [wiki-ui-build]
  pull_request:

jobs:
  build:

    #Static version is used to maintain stability.
    runs-on: ubuntu-18.04

    strategy:
      matrix:
        #Static version is used to maintain stability.
        node-version: [12.17.0]

    steps:
    - name: Clone the repo
      uses: actions/checkout@v2
      with:
        ref: antora-setup
        # Number of commits to fetch. 0 indicates all history.
        fetch-depth: 1

    - name: Use Node.js ${{ matrix.node-version }}
      uses: actions/setup-node@v1
      with:
        node-version: ${{ matrix.node-version }}

    # Display the sha of the build triggering the repository_dispatch event.
    - name: wiki-ui-build
      if: github.event.action == 'wiki-ui-build'
      run: echo wiki-ui-build sha ${{ github.event.client_payload.sha }}

    # Uncomment to write the default package.json file to the repo root.
    # When used in conjunction with the action add-and-commit 'add' command, the
    # file will be written to the repo for editing.
    - name: Install default package.json
      run: npm init --yes

    # Uncomment when adding or updating dependencies in the package-lock.json
    # and package.json files for ci.
    - name: Install Node
      run: npm i

    # Uncomment during initial setup or when updating Antora to a new version.
    # The action add-and-commit 'add' command will detect the changes and commit
    # the package-lock.json and package.json files.
    # Emoji support. Seems to be a direct implementation of AsciiDoctor ruby
    # extension.
    # see: https://github.com/mogztter/asciidoctor-emoji
    - name: Install Antora
      run: |
       npm i @antora/[email protected]
       npm i @antora/[email protected]
       npm i asciidoctor-emoji

    # Uncomment after package-lock.json and package.json files are updated.
#    - name: Run with CI
#      run: npm ci

    - name: Audit Depends
      run: npm audit

#    - name: Build Docs
#      run: npm run buildDocs

    # Detects any updates to package-lock.json and package.json and commits the
    # files to root.
    # see:
    # https://github.com/marketplace/actions/add-commit?version=v4.1.0
    # for use options.
    - name: Commit Packages
      uses: EndBug/add-and-commit@v4
      with:
        author_name: mitm001
        author_email: [email protected]
        message: "Commit files for CI workflow"
        # Commits these files to root if and only if there are changes.
        add: "package-lock.json package.json"
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

    # Commit changes to the gh-pages branch. Antora requires an empty
    # '.nojekyll' be present in the branch due to certain directories starting
    # with an underscore. This action has an option, set by default, to add that
    # file for us on commit.
    # see:
    # https://github.com/marketplace/actions/github-pages-action?version=v3.6.1
    # for use options.
#    - name: Deploy Docs
#      uses: peaceiris/actions-gh-pages@v3
#      with:
#        github_token: ${{ secrets.GITHUB_TOKEN }}
        # Commits these files to gh-pages if and only if there are changes.
#        publish_dir: ./build/site
        # Insert CNAME for repository.
#        cname: wiki.jmonkeyengine.org</code></pre>
</div>
</div>
<div class="paragraph">
<p>The initial main points of interest are as follows.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>repository_dispatch:
  types: [wiki-ui-build]</code></pre>
</div>
</div>
<div class="paragraph">
<p>When the webhook event <code>repository_dispatch</code> is triggered, with a secret <code>WIKI_UI_DISPATCH</code> token that matches the same secret token of this repository and with the <code>event_type</code> &#8220;wiki-ui-build&#8221;, the workflow build will run.</p>
</div>
<div class="paragraph">
<p>See:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><a href="https://developer.github.com/v3/repos/#create-a-repository-dispatch-event" class="bare">https://developer.github.com/v3/repos/#create-a-repository-dispatch-event</a></p>
</li>
<li>
<p><a href="https://blog.marcnuri.com/triggering-github-actions-across-different-repositories/" class="bare">https://blog.marcnuri.com/triggering-github-actions-across-different-repositories/</a></p>
</li>
<li>
<p><a href="https://help.github.com/en/actions/reference/events-that-trigger-workflows#external-events-repository_dispatch" class="bare">https://help.github.com/en/actions/reference/events-that-trigger-workflows#external-events-repository_dispatch</a></p>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>#Static version is used to maintain stability.
runs-on: ubuntu-18.04

strategy:
  matrix:
    #Static version is used to maintain stability.
    node-version: [12.17.0]</code></pre>
</div>
</div>
<div class="paragraph">
<p>With the above lines, we are using a static version of <code>Unbuntu</code> and <code>Node.js</code>. Updates can potentially break things, and we would find out after the fact rather than knowing immediately that there was a problem.</p>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
<div class="paragraph">
<p>Setting the node version using the matrix strategy has the added benefit of appending the Node.js version to our job <code>build</code> on the (GWI) dashboard.</p>
</div>
<div class="paragraph">
<p>For example, our job name <code>build</code>, will have the version <code>12.17.0</code> appended like so:</p>
</div>
<div class="imageblock">
<div class="content">
<img src="_images/vers_append.png" alt="vers_append.png">
</div>
</div>
</td>
</tr>
</table>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>- name: Install default package.json
  run: npm init --yes</code></pre>
</div>
</div>
<div class="paragraph">
<p>The above line will create our default <code>package.json</code> file that will control the (CI) and hold any command line scripts we implement. Once this file is commited to the repo, this line is no longer used.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>- name: Install Node
  run: npm i</code></pre>
</div>
</div>
<div class="paragraph">
<p>This will install node into our workflow and create our initial <code>package-lock.json</code> file. Once the <code>package-lock.json</code> file is committed, this line will only be used to when adding new packages by appending the package name to the command. Change it to <code>run: npm update</code> to update depends.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>- name: Install Antora
  run: |
   npm i @antora/[email protected]
   npm i @antora/[email protected]
   npm i asciidoctor-emoji</code></pre>
</div>
</div>
<div class="paragraph">
<p>The above command will install our Antora depends.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>with:
  author_name: mitm001
  author_email: [email protected]
  message: "Commit files for CI workflow"</code></pre>
</div>
</div>
<div class="paragraph">
<p>The above is the author and message of the commit action. If the author name and email are not set, a warning will be thrown if <code>repository_dispatch</code> triggers a workflow. Customize as needed.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code># Commits these files to root if and only if there are changes.
add: "package-lock.json package.json*"</code></pre>
</div>
</div>
<div class="paragraph">
<p>This line will commit the <code>package-lock.json</code> and <code>package.json</code> if there are any changes to the files.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>env:
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>secrets.GITHUB_TOKEN</code> doesn&#8217;t have authorization to create any successive events, so we avoid an infinite loop of commit, run workflows, commit, run workflows.</p>
</div>
</div>
</div>
</li>
<li>
<p>Add, commit and push the <code>antora-setup</code> branch to the repo. The workflow will commit the <code>package.json</code> and <code>package-lock.json</code> files into the root of the <code>antora-setup</code> branch of the repo.</p>
</li>
</ol>
</div>
</li>
<li>
<p>Issue a pull request. This will pull in the <code>.json</code> files.</p>
</li>
<li>
<p>Edit the <code>main.yml</code> file by commenting out the &#8220;Install default package.json&#8221;, &#8220;Install Node&#8221; and &#8220;Install Antora&#8221; commands.</p>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>#    - name: Install default package.json
#      run: npm init --yes

#    - name: Install Node
#      run: npm i

#    - name: Install Antora
#      run: |
#       npm i @antora/[email protected]
#       npm i @antora/[email protected]
#       npm i asciidoctor-emoji</code></pre>
</div>
</div>
<div class="olist loweralpha">
<ol class="loweralpha" type="a">
<li>
<p>Add, commit and push the <code>antora-setup</code> branch to the repo.</p>
</li>
</ol>
</div>
</li>
<li>
<p>In the Atom Editor:</p>
<div class="olist loweralpha">
<ol class="loweralpha" type="a">
<li>
<p>Edit the <code>package.json</code> file.</p>
<div class="openblock">
<div class="content">
<div class="listingblock">
<div class="title">package.json</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-.json hljs" data-lang=".json">{
  "version": "1.0.1",
  "description": "jMonkeyEngine Documentation",
  "scripts": {
    "buildDocs": "$(npm bin)/antora --stacktrace wiki-playbook.yml"
  },
  "private": true,
  "license": "BSD-3-Clause",

}</code></pre>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
See: <a href="https://nodejs.dev/learn/the-package-json-guide">The Package Json Guide</a>, and <a href="https://nodejs.dev/learn/the-package-lock-json-file">The package-lock.json file</a>  for info on the properties that can be set and their meaning.
</td>
</tr>
</table>
</div>
</div>
</div>
<div class="ulist checklist">
<ul class="checklist">
<li>
<p><i class="fa fa-check-square-o"></i> Bump <code>"version": "1.0.1"</code>.</p>
</li>
<li>
<p><i class="fa fa-check-square-o"></i> Fix the description.</p>
</li>
<li>
<p><i class="fa fa-check-square-o"></i> Remove <code>test</code> from the scripts property.</p>
</li>
<li>
<p><i class="fa fa-check-square-o"></i> Add the <code>buildDocs</code> script.</p>
</li>
<li>
<p><i class="fa fa-check-square-o"></i> Add the <code>"private": true,</code> property.</p>
</li>
<li>
<p><i class="fa fa-check-square-o"></i> Change the license.</p>
</li>
</ul>
</div>
</li>
<li>
<p>Edit the <code>package-lock.json</code> file:</p>
<div class="ulist checklist">
<ul class="checklist">
<li>
<p><i class="fa fa-check-square-o"></i> Bump  <code>"version": "1.0.1"</code>.</p>
</li>
</ul>
</div>
</li>
<li>
<p>Stage, commit and push the <code>package.json</code> and <code>package-lock.json</code> files to the repo.</p>
</li>
</ol>
</div>
</li>
</ol>
</div>
</div>
</div>
<div class="sect1">
<h2 id="preparing-test-site"><a class="anchor" href="#preparing-test-site"></a>Preparing Test Site</h2>
<div class="sectionbody">
<div class="paragraph">
<p>We only need this step for a repository imported from the wiki, skip otherwise.</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>From the (GWI).</p>
<div class="olist loweralpha">
<ol class="loweralpha" type="a">
<li>
<p>Switch to the <code>gh-pages</code> branch and delete the <code>CNAME</code> file.</p>
</li>
<li>
<p>Commit the changes.</p>
</li>
<li>
<p>In the <code>Settings</code> tab, set the newly created branch as the &#8220;Source&#8221; under the GitHub Pages settings. The link box for the site will change color to green, indicating it is configured.</p>
<div class="paragraph">
<p>This will be the branch we deploy the site to using the &#8220;Deploy Docs&#8221; command in the <code>main.yml</code> file.</p>
</div>
</li>
</ol>
</div>
</li>
</ol>
</div>
</div>
</div>
<div class="sect1">
<h2 id="setup-antora"><a class="anchor" href="#setup-antora"></a>Setup Antora</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Add the configuration files. Once complete, our final source structure will look like so.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>|-docs
| |-modules
| | |-ROOT
| |   |-nav.adoc
| |   |-images
| |   |-pages
| |   |-resources
| |-antora.yml
|-wiki-playbook.yml</code></pre>
</div>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>From the Atom Editor:</p>
<div class="olist loweralpha">
<ol class="loweralpha" type="a">
<li>
<p>Add the initial <code>wiki-playbook.yml</code> file to the root of the repo.</p>
<div class="openblock">
<div class="content">
<div class="listingblock">
<div class="title">Initial wiki-playbook.yml</div>
<div class="content">
<pre class="highlightjs highlight"><code>site:
  title: jMonkeyEngine Docs
  url: https://wiki.jmonkeyengine.org
  robots: disallow
  start_page: docs::documentation.adoc
content:
  sources:
  - url: .
    branches: [antora-setup]
    start_path: docs
  - url: https://github.com/jMonkeyEngine/wiki-ui
    branches: HEAD
    start_path: docs
ui:
  bundle:
    url: https://github.com/jMonkeyEngine/wiki-ui/releases/latest/download/ui-bundle.zip
    # Required when using cache or fetch will not update ui.
    snapshot: true
asciidoc:
  # Some built-in AsciiDoc attributes are not applicable in the Antora
  # environment. These attributes include data-uri, allow-uri-read, docinfo,
  # linkcss, noheader, nofooter, webfonts, and outfilesuffix.
  attributes:
    # previous and next page navigation, uses nav.adoc
    page-pagination: ''
    idprefix: ''
    idseparator: '-'
    #add an &lt;orgname&gt; element
    orgname: 'jMonkeyEngine'
    # Site wide setting of javaDoc url. Soft set using '@' allows override at
    # component and page level.
    link-javadoc: 'https://javadoc.jmonkeyengine.org/v3.3.2-stable@'
    # Enables the UI macros (button, menu and kbd)
    experimental: ''
    # Adds an anchor in front of the section title when the mouse cursor hovers
    # over it.
    :sectanchors: ''
  extensions:
  # Twitter Emoji
  # see: https://github.com/Mogztter/asciidoctor-emoji
  - asciidoctor-emoji
runtime:
  cache_dir: ./.cache/antora
  fetch: true</code></pre>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
See: <a href="https://docs.antora.org/antora/2.3/playbook/set-up-playbook/">Set Up a Playbook</a> for detailed <code>key: value</code> explanations.
</td>
</tr>
</table>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
The branches key is set to <code>antora-setup</code>. The <a href="_attachments/wiki-playbook.yml">wiki-playbook.yml</a> in the <code>transition-docs `module is set to use the `master</code> branch for versioning.
</td>
</tr>
</table>
</div>
</div>
</div>
</li>
<li>
<p>Add the <a href="_attachments/antora.yml">antora.yml</a> file to the <code>docs</code> folder. It must be located next to the <code>modules</code> folder.</p>
<div class="listingblock">
<div class="title">antora.yml</div>
<div class="content">
<pre class="highlightjs highlight"><code>name: docs
title: Docs
version: master
start_page: ROOT:jme3.adoc
nav:
- modules/ROOT/nav.adoc</code></pre>
</div>
</div>
</li>
<li>
<p>Add the <code>nav.adoc</code> file to the <code>docs/modules/ROOT</code> folder. It must be in the top-level of the <code>ROOT</code> folder.</p>
<div class="listingblock">
<div class="title">nav.adoc</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">* &lt;&lt;documentation#,Getting Started&gt;&gt;
* {link-javadoc}[JavaDoc]
* &lt;&lt;jme3#,jMonkeyEngine 3&gt;&gt;
** Beginner Tutorials
*** &lt;&lt;jme3/beginner/hello_simpleapplication#,Hello SimpleApplication&gt;&gt;
*** &lt;&lt;jme3/beginner/hello_node#,Hello Node&gt;&gt;
*** &lt;&lt;jme3/beginner/hello_asset#,Hello Asset&gt;&gt;
*** &lt;&lt;jme3/beginner/hello_main_event_loop#,Hello Main Event Loop&gt;&gt;
*** &lt;&lt;jme3/beginner/hello_input_system#,Hello Input System&gt;&gt;
*** &lt;&lt;jme3/beginner/hello_material#,Hello Material&gt;&gt;
*** &lt;&lt;jme3/beginner/hello_animation#,Hello Animation&gt;&gt;
*** &lt;&lt;jme3/beginner/hello_picking#,Hello Picking&gt;&gt;
*** &lt;&lt;jme3/beginner/hello_collision#,Hello Collision&gt;&gt;
*** &lt;&lt;jme3/beginner/hello_terrain#,Hello Terrain&gt;&gt;
*** &lt;&lt;jme3/beginner/hello_audio#,Hello Audio&gt;&gt;
*** &lt;&lt;jme3/beginner/hello_effects#,Hello Effects&gt;&gt;
*** &lt;&lt;jme3/beginner/hello_physics#,Hello Physics&gt;&gt;
** Intermediate Tutorials
*** Concepts
**** &lt;&lt;jme3/intermediate/best_practices#,Best Practices&gt;&gt;
**** &lt;&lt;jme3/intermediate/simpleapplication#,Simple Application&gt;&gt;
**** &lt;&lt;jme3/features#,Features&gt;&gt;
**** &lt;&lt;jme3/intermediate/optimization#,Optimization&gt;&gt;
**** &lt;&lt;jme3/faq#,FAQ&gt;&gt;
*** Math Concepts
**** &lt;&lt;jme3/math_for_dummies#,Math For Dummies&gt;&gt;
**** &lt;&lt;jme3/intermediate/math#,Math&gt;&gt;
**** &lt;&lt;jme3/math#,More Math&gt;&gt;
**** &lt;&lt;jme3/rotate#,Rotate&gt;&gt;
**** &lt;&lt;jme3/math_video_tutorials#,Math Video Tutorials&gt;&gt;
*** 3D Graphics Concepts
**** &lt;&lt;jme3/intermediate/multi-media_asset_pipeline#,Multi-Media Asset Pipeline&gt;&gt;
**** &lt;&lt;jme3/scenegraph_for_dummies#,Scenegraph for Dummies&gt;&gt;
**** &lt;&lt;jme3/beginner/hellovector#,Hello Vector&gt;&gt;
**** &lt;&lt;jme3/terminology#,Terminology&gt;&gt;
**** &lt;&lt;jme3/intermediate/how_to_use_materials#,How to Use Materials&gt;&gt;
**** &lt;&lt;jme3/intermediate/transparency_sorting#,Transparency and Sorting&gt;&gt;
**** &lt;&lt;jme3/external/blender#,Importing from Blender&gt;&gt;
**** &lt;&lt;jme3/external/3dsmax#,Importing from 3DS Max&gt;&gt;
* &lt;&lt;logo#,Logo Usage&gt;&gt;
* &lt;&lt;bsd_license#,License&gt;&gt;
* &lt;&lt;github_tips#,Github Tips&gt;&gt;

.SDK
* &lt;&lt;sdk#,jMonkeyEngine SDK&gt;&gt;</code></pre>
</div>
</div>
</li>
<li>
<p>Stage, commit and push everything to the repo.</p>
</li>
</ol>
</div>
</li>
<li>
<p>From the (CLI):</p>
<div class="olist loweralpha">
<ol class="loweralpha" type="a">
<li>
<p>Edit the main.yml file, uncommenting the <code>Run with CI</code>, <code>Build Docs</code>, <code>Deploy Docs</code> commands. If this is for the official wiki site, uncomment the <code>cname</code> key as well.</p>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>    - name: Run with CI
      run: npm ci

    - name: Build Docs
      run: npm run buildDocs

    - name: Deploy Docs
      uses: peaceiris/actions-gh-pages@v3
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        # Commits these files to gh-pages if and only if there are changes.
        publish_dir: ./build/site
        # Insert CNAME for repository.
        cname: wiki.jmonkeyengine.org</code></pre>
</div>
</div>
</li>
<li>
<p>Add, commit and push the <code>antora-setup</code> branch to the repo.</p>
</li>
</ol>
</div>
</li>
</ol>
</div>
<div class="paragraph">
<p>The build will succeed but if we examine the log file we find that the emoji.adoc page is broken. This is due to format changes using the new emoji macro.</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Issue a pull request from the Atom Editor.</p>
</li>
<li>
<p>To save time, replace the <code>docs/modules/ROOT/pages/wiki/emoji.adoc</code> file with the <code>emoji.adoc</code> file found inside <code>transition-docs</code> module.</p>
</li>
</ol>
</div>
<div class="paragraph">
<p>We are now down to one last set of warnings that need attention. When we examine the build log we see:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">WARNING: skipping reference to missing attribute: home
WARNING: skipping reference to missing attribute: appname
WARNING: skipping reference to missing attribute: home
WARNING: skipping reference to missing attribute: appname
WARNING: skipping reference to missing attribute: 0
WARNING: skipping reference to missing attribute: 1
WARNING: skipping reference to missing attribute: 2</code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>home</code> and <code>appname</code> missing attributes are due to unescaped content in the <code>docs/modules/ROOT/pages/sdk/update_center.adoc</code> file. This folder will be removed in the future but to stop the errors for now, fix the offending content.</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Escape one of the brackets in each string <code>${HOME}</code> and <code>${APPNAME}</code>.</p>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>"`$pass:[{]HOME}/.$pass:[{]APPNAME}/version`"
"`$pass:[{]HOME}/.$pass:[{]APPNAME}/nightly`"</code></pre>
</div>
</div>
</li>
<li>
<p>The second set of warning comes from the <code>docs/modules/ROOT/pages/jme3/advanced/logging.adoc</code> file. To fix this, look for and escape the string <code>{0},{1},{2}</code>.</p>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>`++{0},{1},{2}++`</code></pre>
</div>
</div>
</li>
<li>
<p>Stage, commit and push everything to the repo after editing.</p>
</li>
</ol>
</div>
</div>
</div>
<div class="sect1">
<h2 id="cleanup"><a class="anchor" href="#cleanup"></a>Cleanup</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Delete the following from the <code>antora-setup</code> branch:</p>
</div>
<div class="ulist checklist">
<ul class="checklist">
<li>
<p><i class="fa fa-check-square-o"></i> .editorconfig</p>
</li>
<li>
<p><i class="fa fa-check-square-o"></i> .gitignore</p>
</li>
<li>
<p><i class="fa fa-check-square-o"></i> .travis.yml</p>
</li>
<li>
<p><i class="fa fa-check-square-o"></i> build.gradle</p>
</li>
<li>
<p><i class="fa fa-check-square-o"></i> deploy_ghpages.sh</p>
</li>
<li>
<p><i class="fa fa-check-square-o"></i> gradlew</p>
</li>
<li>
<p><i class="fa fa-check-square-o"></i> gradle.bat</p>
</li>
<li>
<p><i class="fa fa-check-square-o"></i> src directory (slim templates)</p>
</li>
<li>
<p><i class="fa fa-check-square-o"></i> lib directory</p>
</li>
<li>
<p><i class="fa fa-check-square-o"></i> gradle/wrapper</p>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Add the new README.adoc file from the <code>transition-docs</code> module to the root of the repository.</p>
</li>
<li>
<p>Stage, commit and push everything to the repo after editing.</p>
</li>
</ol>
</div>
</li>
</ul>
</div>
</div>
</div>
<div class="sect1">
<h2 id="merge-to-master"><a class="anchor" href="#merge-to-master"></a>Merge to Master</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Once testing reveals everything is correctly setup, change the following settings to prepare for the final step of merging the antora-setup branch into master.</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Change the following settings:</p>
<div class="olist loweralpha">
<ol class="loweralpha" type="a">
<li>
<p>Set the <code>branches:</code> value <code>antora-setup</code> to <code>master</code></p>
<div class="openblock">
<div class="content">
<div class="listingblock">
<div class="title">main.yml</div>
<div class="content">
<pre class="highlightjs highlight"><code>on:
  push:
    branches: '*'</code></pre>
</div>
</div>
<div class="paragraph">
<p>and remove the <code>ref: antora-setup</code> from the  <code>Clone the repo</code> command.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>steps:
- name: Clone the repo
  uses: actions/checkout@v2
  with:
    # Number of commits to fetch. 0 indicates all history.
    fetch-depth: 1</code></pre>
</div>
</div>
</div>
</div>
</li>
<li>
<p>Set the <code>branches: [antora-setup]</code> value in the <code>wiki-playbook.yml</code> to point to HEAD.</p>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>content:
  sources:
  - url: .
    branches: HEAD</code></pre>
</div>
</div>
</li>
</ol>
</div>
</li>
<li>
<p>Add, commit and push the <code>antora-setup</code> branch to the repository.</p>
</li>
<li>
<p>Checkout the master branch, merge the <code>antora-setup</code> branch to <code>master</code> and push to the repository.</p>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>git checkout master
git merge antora-setup
git push origin master</code></pre>
</div>
</div>
</li>
<li>
<p>Delete the <code>antora-setup</code> setup branch.</p>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>git push -d origin antora-setup</code></pre>
</div>
</div>
</li>
</ol>
</div>
</div>
</div>
<div class="sect1">
<h2 id="post-rename-cache-commit"><a class="anchor" href="#post-rename-cache-commit"></a>Post Rename Cache Commit</h2>
<div class="sectionbody">
<div class="paragraph">
<p>After the branch rename, change the workflow file <code>EndBug/add-and-commit@v4</code> &#8220;add&#8221; command to commit the cache upon changes.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code># Commits these files to root if and only if there are changes.
add: "package-lock.json package.json ./.cache/antora/*"</code></pre>
</div>
</div>
<div class="paragraph">
<p>After add, commit and pushing the workflow file, the cache will be committed to the repository master branch.</p>
</div>
</div>
</div>
</article>
<aside class="toc sidebar" data-title="Contents" data-levels="2">
  <div class="toc-menu"></div>
</aside>
  </div>
</main>
</div>
<footer class="footer">
  <p>This page was built using the Antora default UI.</p>
  <p>The source code for this UI is licensed under the terms of the MPL-2.0 license.</p>
</footer>
<script src="../../_/js/site.js"></script>
<script async src="../../_/js/vendor/highlight.js"></script>
  </body>
</html>