#5 📝 GitHub Pages setup and tranche 1 of docs

.github/workflows/publish.yml

@@ -1,24 +1,50 @@
 name: Publish to GitHub Pages
+
 on:
+  # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
+
+  # Runs on pushes targeting the following branch(es)
   push:
-    branches: [dev]
+    branches: [dev,5-migrate-documentation]
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
 jobs:
-  build:
+  # Single deploy job since we're just deploying
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
       - name: Install Node.js
         uses: actions/setup-node@v2
         with:
-          node-version: '16'
+          node-version: '20'
       - name: Install Antora
         run: npm i antora
       - name: Generate Site
         run: GIT_CREDENTIALS="https://${{ secrets.PAT }}:@github.com" npx antora docs/antora-playbook.yml
-      - name: Publish to GitHub Pages
-        uses: peaceiris/actions-gh-pages@v3
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
         with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: docs/build/site
+          # Upload entire repository
+          path: docs/build/site
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

README.md

@@ -1,5 +1,6 @@
 # aiSSEMBLE™
-
+[![Documentation](https://img.shields.io/badge/documentation-GitHub_Pages-blue)](https://boozallen.github.io/aissemble/current-dev/index.html)
+[![Publish to GitHub Pages](https://github.com/boozallen/aissemble/actions/workflows/publish.yml/badge.svg)](https://github.com/boozallen/aissemble/actions/workflows/publish.yml)
 ## aiSSEMBLE Overview
 
 ### Purpose of the aiSSEMBLE

docs/CONTRIBUTING.md

@@ -0,0 +1,71 @@
+# Contributing to the aiSSEMBLE™ Docs
+
+## Rationale 
+Because our aiSSEMBLE docs cover a variety of modules, it is important that consistent standards are developed and 
+strictly adhered to. Navigable and relevant documentation a critical enabler for daily use. To that end, this 
+document aims to capture those standards and lay them out clearly so that all future contributors are adhering to the 
+established patterns.
+
+## Guiding Principles
+The most important guiding principles are the following:
+ * The documentation is NOT a demonstrable guide, rather this is a specification guide.
+ * The intent for this documentation is to be consumed by aiSSEMBLE users. The usage by maintainers is incidental.
+
+Some additional guiding principles you should follow whilst working on the aiSSEMBLE docs include:
+ * Document code as close to the native format as possible rather (_e.g. Javadocs_).
+ * Delegate to external documentation wherever possible. 
+ * Follow the “_what_, _why_ and _how_” approach:
+   * What is it that you’re touching on - rely on official documentation (external links).
+   * Why does aiSSEMBLE use it.
+   * How does aiSSEMBLE use it.
+ * Every page should have an overview to help the reader quickly determine applicability of the material.
+
+## Standards
+These are the standards derived from the principles above that provide specific guidance.
+
+### Markup Standards:
+ * Be cautious on identifying when to use an ordered vs. unordered list.
+   * Use ordered when going through a sequence (e.g. _1_, _2_, _3_ or _a_, _b_, _c_).
+   * Use unordered when listing out items in a list.
+ * Ensure to wrap the lines of code within your .adoc files; ~100-120 characters.
+ * When documenting file paths, use angled brackets (e.g. `<project>/<project>-pipeline-models/src/main/resources/records/`).
+ * Use `xref:<page-name>` to link within the docs (e.g. `xref:pipeline.adoc`).
+   * Excluding version/module name ensures the links always work correctly.
+ * Ensure external links open in a new window for consistency (e.g. `<url>[<text>,role=external,window=_blank]`).
+ * Wiki links are prone to break on rename if you just copy them from the address bar. There are two ways to prevent this:
+   * Use the Share button to generate a short URL that follows page renames (preferred).
+   * Click the edit icon, grab the url and replace `editaction` with `viewaction`.
+   * When referencing the version of aiSSEMBLE, use the macro `{page-version}`. This excludes `-SNAPSHOT` for prereleases. 
+     See [archetype.adoc](modules/ROOT/pages/archetype.adoc) for an example of including the `-SNAPSHOT` suffix.
+### Process Standards:
+ * Follow standard ticket workflow .
+ * Contribute to the [Graphic Repository](<NB: OSS: need new location for graphic repository>) when adding graphics to the docs.
+   * **Step 1:** Copy and paste the original PowerPoint slide and make any necessary changes to that slide within the "_**Graphic-Repository.pptx**_".
+   * **Step 2:** The slide following the slide with the graphic, place the link of the original slide.
+ * For existing pages, hold a review of the existing content and address feedback based on that.
+
+### Content Standards: 
+ * When documenting files and code, use the following examples:
+   * For Records: 
+     * Name: _TaxPayer_
+     * Field Name: _ssn_
+   * For Dictionary:
+     * Name: _IrsDictionary_
+     * Type Name: _SocialSecurityNumber_
+   * For Pipelines: _TaxPayerPipeline_
+ * Structure the headings with present participle verbs (e.g. Creating a Project, Deploying a Project, etc.).
+ * Only include files that are a direct result of relevant component in the What Gets Generated section (e.g. 
+   `SchemaBase` is NOT a direct result of Data Validation; DataAccessResource is a direct result of the Data Access 
+   component).
+ * Follow the standards for api documentation:
+   * Java – Javadocs
+   * Python – Javadocs
+   * REST – Swagger
+   * GraphQL - [Hackernoon](https://hackernoon.com/documenting-graphql-apis)
+ * Document current functionality only, avoid annotating any upcoming features even if expected in the immediate future!
+
+## Antora
+aiSSEMBLE Docs utilizes Antora for its static-site generator. Antora helps create documentation websites from AsciiDoc 
+source files stored in one or more source control repository. Refer to the [Antora documentation](https://docs.antora.org/antora/latest/) 
+for quick tips and how-to.
+

docs/antora-aissemble-ui/.editorconfig

@@ -0,0 +1,9 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true

docs/antora-aissemble-ui/.eslintrc

@@ -0,0 +1,14 @@
+{
+  "extends": "standard",
+  "rules": {
+    "arrow-parens": ["error", "always"],
+    "comma-dangle": ["error", {
+      "arrays": "always-multiline",
+      "objects": "always-multiline",
+      "imports": "always-multiline",
+      "exports": "always-multiline"
+    }],
+    "max-len": [1, 120, 2],
+    "spaced-comment": "off"
+  }
+}

docs/antora-aissemble-ui/.gulp.json

@@ -0,0 +1,4 @@
+{
+  "description": "Build tasks for the Antora default UI project",
+  "flags.tasksDepth": 1
+}

docs/antora-aissemble-ui/.nvmrc

@@ -0,0 +1 @@
+10

docs/antora-aissemble-ui/.stylelintrc

@@ -0,0 +1,7 @@
+{
+  "extends": "stylelint-config-standard",
+  "rules": {
+    "comment-empty-line-before": null,
+    "no-descending-specificity": null,
+  }
+}