Improve doc

.github/workflows/ghpages.yml

@@ -31,11 +31,11 @@ jobs:
           distribution: 'temurin'
           architecture: x64
       - name: Generate
-        run: ./gradlew asciidoctor
+        run: ./gradlew antora
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v2
         with:
-          path: ./build/docs/asciidoc
+          path: ./build/site
 
   publish-ghpages:
     needs: build

antora-playbook.yml

@@ -0,0 +1,14 @@
+site:
+  title: Nextflow Nomad executor
+  start_page: main:ROOT:index.adoc
+content:
+  sources:
+    - url: .
+      start_path: ./src/docs/antora
+      edit_url: false
+      branches: HEAD
+
+ui:
+  bundle:
+    url: ./src/docs/antora/ui
+    snapshot: true

build.gradle

@@ -5,7 +5,7 @@ buildscript {
 }
 
 plugins {
-    id("org.asciidoctor.jvm.convert") version "3.3.2"
+    id 'org.antora' version '1.0.0'
 }
 
 repositories {
@@ -22,7 +22,18 @@ nextflowPlugin{
     ]
 }
 
-asciidoctor{
-    baseDir 'src/docs/asciidoc'
-    attributes revnumber : { project.version.toString() }
+node {
+    version = 'latest'
+}
+
+antora {
+    version = '3.0.3'
+    options = [
+            clean: true,
+            fetch: true,
+            stacktrace: true,
+            attributes: [product: 'Nf-Nomad Plugin']
+    ]
+    environment = [:]
+    packages = [:]
 }

src/docs/antora/antora.yml

@@ -0,0 +1,5 @@
+name: main
+version: final
+title: nf-nomad
+nav:
+  - modules/ROOT/nav.adoc

src/docs/antora/modules/ROOT/nav.adoc

@@ -0,0 +1,9 @@
+
+* xref:index.adoc[Introduction]
+
+* xref:usage.adoc[Usage]
+
+* xref:config.adoc[Configuration]
+
+* xref:development.adoc[Development]
+

src/docs/antora/modules/ROOT/pages/config.adoc

@@ -0,0 +1,25 @@
+== Configuration
+
+Most of the basic configuration is in a `nomad` closure in the `nextflow.config` file
+
+i.e.
+
+```
+nomad{
+    client{
+        address = "http://localhost:4646"
+    }
+    jobs{
+        deleteoncompletion = false
+    }
+}
+```
+
+=== Client configuration
+
+- address, a URL
+- token, if the cluster is protected you must to provide a token
+
+=== Jobs configuration
+
+- deleteOnCompletion, a boolean indicating if the job will be removed once completed

src/docs/asciidoc/parts/intro.adoc → src/docs/antora/modules/ROOT/pages/index.adoc

@@ -7,8 +7,9 @@ The plugin itself is similar in design and scope to other executor integrations
 Hope you enjoy using the plugin and please participate in the development/feedback of the plugin in the `platform-nomad` channel on the Nextflow Slack instance. We would love to hear your feedback!
 
 
+=== Resources
 
-==== Some resources for familiarizing yourself with Nomad:
+Some resources for familiarizing yourself with Nomad:
 
 - https://developer.hashicorp.com/nomad/docs?product_intent=nomad[Hashicorp Documentation website for Nomad]
 

src/docs/asciidoc/parts/usage.adoc → src/docs/antora/modules/ROOT/pages/usage.adoc

@@ -64,9 +64,9 @@ workflow {
 }
 ----
 
-TIP:: You need to use an S3 bucket as working dir
+TIP: You need to use an S3 bucket as working dir
 
 Run the pipeline
 
-`$ nextflow run main.nf`
+`$ nextflow run main.nf -w s3://YOUR_BUCKET`
 

src/docs/antora/ui/helpers/and.js

@@ -0,0 +1,9 @@
+'use strict'
+
+module.exports = (...args) => {
+  const numArgs = args.length
+  if (numArgs === 3) return args[0] && args[1]
+  if (numArgs < 3) throw new Error('{{and}} helper expects at least 2 arguments')
+  args.pop()
+  return args.every((it) => it)
+}

src/docs/antora/ui/helpers/detag.js

@@ -0,0 +1,5 @@
+'use strict'
+
+const TAG_ALL_RX = /<[^>]+>/g
+
+module.exports = (html) => html && html.replace(TAG_ALL_RX, '')

src/docs/antora/ui/helpers/eq.js

@@ -0,0 +1,3 @@
+'use strict'
+
+module.exports = (a, b) => a === b

src/docs/antora/ui/helpers/increment.js

@@ -0,0 +1,3 @@
+'use strict'
+
+module.exports = (value) => (value || 0) + 1

src/docs/antora/ui/helpers/ne.js

@@ -0,0 +1,3 @@
+'use strict'
+
+module.exports = (a, b) => a !== b

src/docs/antora/ui/helpers/not.js

@@ -0,0 +1,3 @@
+'use strict'
+
+module.exports = (val) => !val

src/docs/antora/ui/helpers/or.js

@@ -0,0 +1,9 @@
+'use strict'
+
+module.exports = (...args) => {
+  const numArgs = args.length
+  if (numArgs === 3) return args[0] || args[1]
+  if (numArgs < 3) throw new Error('{{or}} helper expects at least 2 arguments')
+  args.pop()
+  return args.some((it) => it)
+}

src/docs/antora/ui/helpers/relativize.js

@@ -0,0 +1,24 @@
+'use strict'
+
+const { posix: path } = require('path')
+
+module.exports = (to, from, ctx) => {
+  if (!to) return '#'
+  // NOTE only legacy invocation provides both to and from
+  if (!ctx) from = (ctx = from).data.root.page.url
+  if (to.charAt() !== '/') return to
+  if (!from) return (ctx.data.root.site.path || '') + to
+  let hash = ''
+  const hashIdx = to.indexOf('#')
+  if (~hashIdx) {
+    hash = to.substr(hashIdx)
+    to = to.substr(0, hashIdx)
+  }
+  return to === from
+    ? hash || (isDir(to) ? './' : path.basename(to))
+    : (path.relative(path.dirname(from + '.'), to) || '.') + (isDir(to) ? '/' + hash : hash)
+}
+
+function isDir (str) {
+  return str.charAt(str.length - 1) === '/'
+}

src/docs/antora/ui/helpers/year.js

@@ -0,0 +1,3 @@
+'use strict'
+
+module.exports = () => new Date().getFullYear().toString()

src/docs/antora/ui/layouts/404.hbs

@@ -0,0 +1,11 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+{{> head defaultPageTitle='Page Not Found'}}
+  </head>
+  <body class="status-404">
+{{> header}}
+{{> body}}
+{{> footer}}
+  </body>
+</html>

src/docs/antora/ui/layouts/default.hbs

@@ -0,0 +1,11 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+{{> head defaultPageTitle='Untitled'}}
+  </head>
+  <body class="article{{#with (or page.attributes.role page.role)}} {{{this}}}{{/with}}">
+{{> header}}
+{{> body}}
+{{> footer}}
+  </body>
+</html>

src/docs/antora/ui/partials/article-404.hbs

@@ -0,0 +1,10 @@
+<article class="doc">
+<h1 class="page">{{{or page.title 'Page Not Found'}}}</h1>
+<div class="paragraph">
+<p>The page you&#8217;re looking for does not exist. It may have been moved. You can{{#with site.homeUrl}} return to the <a href="{{{this}}}">start page</a>, or{{/with}} follow one of the links in the navigation to the left.</p>
+</div>
+<div class="paragraph">
+<p>If you arrived on this page by clicking on a link, please notify the owner of the site that the link is broken.
+If you typed the URL of this page manually, please double check that you entered the address correctly.</p>
+</div>
+</article>

src/docs/antora/ui/partials/article.hbs

@@ -0,0 +1,7 @@
+<article class="doc">
+{{#with page.title}}
+<h1 class="page">{{{this}}}</h1>
+{{/with}}
+{{{page.contents}}}
+{{> pagination}}
+</article>

src/docs/antora/ui/partials/body.hbs

@@ -0,0 +1,4 @@
+<div class="body">
+{{> nav}}
+{{> main}}
+</div>

src/docs/antora/ui/partials/breadcrumbs.hbs

@@ -0,0 +1,20 @@
+<nav class="breadcrumbs" aria-label="breadcrumbs">
+  {{#if page.breadcrumbs}}
+  <ul>
+    {{#with page.componentVersion}}
+    {{#if (and ./title (ne ./title @root.page.breadcrumbs.0.content))}}
+    <li><a href="{{{relativize ./url}}}">{{{./title}}}</a></li>
+    {{/if}}
+    {{/with}}
+    {{#each page.breadcrumbs}}
+    <li>
+    {{~#if (and ./url (eq ./urlType 'internal'))~}}
+    <a href="{{{relativize ./url}}}">{{{./content}}}</a>
+    {{~else~}}
+    {{{./content}}}
+    {{~/if~}}
+    </li>
+    {{/each}}
+  </ul>
+  {{/if}}
+</nav>

src/docs/antora/ui/partials/footer-content.hbs

@@ -0,0 +1,3 @@
+<footer class="footer">
+  <p>This site was built using Antora.</p>
+</footer>

src/docs/antora/ui/partials/footer-scripts.hbs

@@ -0,0 +1,5 @@
+<script src="{{{uiRootPath}}}/js/site.js"></script>
+<script async src="{{{uiRootPath}}}/js/vendor/highlight.js"></script>
+{{#if env.SITE_SEARCH_PROVIDER}}
+{{> search-scripts}}
+{{/if}}

src/docs/antora/ui/partials/footer.hbs

@@ -0,0 +1,2 @@
+{{> footer-content}}
+{{> footer-scripts}}

src/docs/antora/ui/partials/head-icons.hbs

@@ -0,0 +1 @@
+    {{!-- <link rel="icon" href="{{{uiRootPath}}}/img/favicon.ico" type="image/x-icon"> --}}

src/docs/antora/ui/partials/head-info.hbs

@@ -0,0 +1,20 @@
+    {{#with page.canonicalUrl}}
+    <link rel="canonical" href="{{{this}}}">
+    {{/with}}
+    {{#unless (eq page.attributes.pagination undefined)}}
+    {{#with page.previous}}
+    <link rel="prev" href="{{{relativize ./url}}}">
+    {{/with}}
+    {{#with page.next}}
+    <link rel="next" href="{{{relativize ./url}}}">
+    {{/with}}
+    {{/unless}}
+    {{#with page.description}}
+    <meta name="description" content="{{{detag this}}}">
+    {{/with}}
+    {{#with page.keywords}}
+    <meta name="keywords" content="{{{this}}}">
+    {{/with}}
+    {{#with (or antoraVersion site.antoraVersion)}}
+    <meta name="generator" content="Antora {{{this}}}">
+    {{/with}}

src/docs/antora/ui/partials/head-meta.hbs

@@ -0,0 +1 @@
+    {{!-- Add additional meta tags here --}}

src/docs/antora/ui/partials/head-prelude.hbs

@@ -0,0 +1,2 @@
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width,initial-scale=1">

src/docs/antora/ui/partials/head-scripts.hbs

@@ -0,0 +1,5 @@
+    {{#with site.keys.googleAnalytics}}
+    <script async src="https://www.googletagmanager.com/gtag/js?id={{this}}"></script>
+    <script>function gtag(){dataLayer.push(arguments)};window.dataLayer=window.dataLayer||[];gtag('js',new Date());gtag('config','{{this}}')</script>
+    {{/with}}
+    <script>var uiRootPath = '{{{uiRootPath}}}'</script>

src/docs/antora/ui/partials/head-styles.hbs

@@ -0,0 +1,2 @@
+<link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.6.1/css/all.css">
+<link rel="stylesheet" href="{{{uiRootPath}}}/css/site.css">