feat(PCTSEC-208): documentation skeleton

.gitignore

@@ -0,0 +1,2 @@
+build
+node_modules

antora-playbook.yml

@@ -0,0 +1,32 @@
+#
+# JBoss, Home of Professional Open Source.
+# Copyright 2023 Red Hat, Inc., and individual contributors
+# as indicated by the @author tags.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+site:
+  title: Mequal Documentation
+  start_page: docs::index.adoc
+content:
+  sources:
+    - url: ./
+      branches: HEAD
+      start_path: docs
+      edit_url: false
+ui:
+  supplemental_files: ./docs/ui
+  bundle:
+    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
+    snapshot: true

docs/antora.yml

@@ -0,0 +1,28 @@
+#
+# JBoss, Home of Professional Open Source.
+# Copyright 2023 Red Hat, Inc., and individual contributors
+# as indicated by the @author tags.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+name: docs
+title: Mequal Documentation
+version: latest
+
+start_page: ROOT:index.adoc
+
+nav:
+  - modules/ROOT/nav.adoc
+  - modules/getting-started/nav.adoc
+  - modules/handbook/nav.adoc

docs/modules/ROOT/nav.adoc

@@ -0,0 +1,2 @@
+* xref:index.adoc[]
+

docs/modules/ROOT/pages/index.adoc

@@ -0,0 +1,13 @@
+= Mequal
+:navtitle: Welcome
+
+> In policy we trust!
+
+== About
+
+TBD
+
+== Resources
+
+* xref:getting-started:index.adoc[Getting Started]
+* xref:handbook:index.adoc[Handbook]

docs/modules/ROOT/partials/wip.adoc

@@ -0,0 +1,4 @@
+[WARNING]
+====
+This page is work in progress.
+====

docs/modules/getting-started/nav.adoc

@@ -0,0 +1 @@
+* xref:index.adoc[Getting Started]

docs/modules/getting-started/pages/index.adoc

@@ -0,0 +1,3 @@
+= Getting Started
+
+include::ROOT:partial$wip.adoc[]

docs/modules/handbook/nav.adoc

@@ -0,0 +1 @@
+* xref:index.adoc[Handbook]

docs/modules/handbook/pages/index.adoc

@@ -0,0 +1,4 @@
+= Handbook
+
+include::ROOT:partial$wip.adoc[]
+

docs/ui/partials/header-content.hbs

@@ -0,0 +1,21 @@
+<header class="header">
+  <nav class="navbar">
+    <div class="navbar-brand">
+      <a class="navbar-item" href="{{{or site.url siteRootPath}}}">{{site.title}}</a>
+      {{#if env.SITE_SEARCH_PROVIDER}}
+      <div class="navbar-item search hide-for-print">
+        <div id="search-field" class="field">
+          <input id="search-input" type="text" placeholder="Search the docs"{{#if page.home}} autofocus{{/if}}>
+        </div>
+      </div>
+      {{/if}}
+      <button class="navbar-burger" aria-controls="topbar-nav" aria-expanded="false" aria-label="Toggle main menu">
+        <span></span>
+        <span></span>
+        <span></span>
+      </button>
+    </div>
+    <div id="topbar-nav" class="navbar-menu">
+    </div>
+  </nav>
+</header>

gulpfile.js

@@ -0,0 +1,67 @@
+/*
+ * JBoss, Home of Professional Open Source.
+ * Copyright 2023 Red Hat, Inc., and individual contributors
+ * as indicated by the @author tags.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+"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,
+  host: "0.0.0.0",
+  port: 4000,
+  root: outputDir,
+};
+const antoraArgs = ["--clean", "--playbook", playbookFilename];
+const watchPatterns = playbook.content.sources
+  .filter((source) => !source.url.includes(":"))
+  .reduce((accum, source) => {
+    accum.push(`./docs/antora.yml`);
+    accum.push(`./docs/modules/**/*`);
+    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) };

hack/docs-generate.sh

@@ -0,0 +1,27 @@
+#!/bin/env bash
+
+#
+# JBoss, Home of Professional Open Source.
+# Copyright 2023 Red Hat, Inc., and individual contributors
+# as indicated by the @author tags.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+set -e
+
+SCRIPT_DIR=$(dirname "$0")
+
+set -x
+
+exec npx antora --clean --fetch "${SCRIPT_DIR}"/../antora-playbook.yml

hack/docs-preview.sh

@@ -0,0 +1,24 @@
+#!/bin/env bash
+
+#
+# JBoss, Home of Professional Open Source.
+# Copyright 2023 Red Hat, Inc., and individual contributors
+# as indicated by the @author tags.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+set -e
+set -x
+
+exec npx gulp