From eab74b8200fd7af0e496ec3a472c3d7e1a9dbe53 Mon Sep 17 00:00:00 2001
From: James Read <contact@jread.com>
Date: Tue, 25 Feb 2020 16:06:40 +0100
Subject: [PATCH] Publish docs/*.adoc's into into GitHub pages pretty HTML (#1181)

---
 docs/Creating_a_config.adoc              |   11 +-
 docs/Supported_Cloud_Providers.adoc      |    4 +
 .github/workflows/asciidoc.yml           |   30 +++++++
 docs/FAQ.adoc                            |   20 ++--
 docs/Creating_an_OpenShift_Workload.adoc |    4 
 docs/Contributing.adoc                   |   44 ++++++-----
 docs/Creating_a_cloud_deployer.adoc      |    4 +
 docs/Preparing_your_workstation.adoc     |   31 +++----
 docs/User_stories.adoc                   |    2 
 docs/Makefile                            |    5 +
 docs/README.adoc                         |   41 ++++++----
 11 files changed, 125 insertions(+), 71 deletions(-)

diff --git a/.github/workflows/asciidoc.yml b/.github/workflows/asciidoc.yml
new file mode 100644
index 0000000..570c931
--- /dev/null
+++ b/.github/workflows/asciidoc.yml
@@ -0,0 +1,30 @@
+name: build adocs
+
+on:
+  push:
+    branches:
+    - development
+
+jobs:
+  adoc_build:
+    runs-on: ubuntu-latest
+    name: Asciidoctoring the docs to pretty HTML!
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v2
+
+    - name: Get build container
+      id: adocbuild
+      uses: avattathil/asciidoctor-action@master
+      with:
+          program: "asciidoctor -D public/ --backend=html5 -o index.html docs/README.adoc"
+
+    - name: Print execution time
+      run: echo "Time ${{ steps.adocbuild.outputs.time }}"
+
+    - name: Deploy docs to ghpages
+      uses: peaceiris/actions-gh-pages@v3
+      with: 
+        deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
+        publish_branch: gh-pages
+        publish_dir: ./public/
diff --git a/docs/CONTRIBUTING.md b/docs/Contributing.adoc
similarity index 77%
rename from docs/CONTRIBUTING.md
rename to docs/Contributing.adoc
index dfc2991..69fe246 100644
--- a/docs/CONTRIBUTING.md
+++ b/docs/Contributing.adoc
@@ -1,19 +1,19 @@
-Contributing to Ansible Agnostic Deployer
-================
+== Contributing 
 
 If you're reading this, hopefully you are considering helping out with the Ansible Agnostic Deployer for Red Hat enablement.
 
 Herein lies the contribution guidelines for helping out with this project. Do take the guidelines here literally, if you find issue with any of them or you see room for improvement, please let us know via a GitHub issue.
 
-## Rules ##
+=== Rules
 
-* The Ansible [Code of Conduct][coc] still applies.
-* For git messages, branch names, ..., follow [Git Style Guide][gitstyle].
+* The Ansible <<coc,Code of Conduct>> still applies.
+* For git messages, branch names, ..., follow <<gitstyle,Git Style Guide>>
 * Should you wish to work on a completely new standard, GREAT, but please file an issue for tracking.
 * To contribute, fork and make a pull request against the `development` branch.
 * All tasks should be in YAML literal.
 
-```yml
+[source,xml]
+----
 # This
 - name: Create a directory
   file:
@@ -23,21 +23,23 @@
 # Not this
 - name: Create a directory
   file: state=directory path=/tmpt/deletethis
-```
+----
 
 * There should be no space before a task hyphen
 
-```yml
+[source,yml]
+----
 # This
 - name: Do something
 
 # Not this
    - name: Do something
-```
+----
 
 * Module arguments should be indented two spaces
 
-```yml
+[source,yml]
+----
 # This
 - name: Create a directory
   file:
@@ -49,12 +51,13 @@
   file:
       state: directory
       path: /tmp/deletethis
-```
+----
 
 * There should be a single line break between tasks
 * Tags should be in multi-line format and indented two spaces just like module arguments above
 
-```yml
+[source,xml]
+----
 # This
 - name: "Check hosts.equiv"
   stat:
@@ -73,21 +76,22 @@
   register: hosts_equiv_audit
   always_run: yes
   tags: [tag1,tag2]
-```
+----
 
 * Every task must be named and provide brief descriptions about the task being accomplished.
 
-### Git ###
-Please follow [Git style guide][gitstyle].
+=== Git
+
+Please follow the <<gitstyle,Git style guide>>.
 
 Note: during the review process, you may add new commits to address review comments or change existing commits. However, before getting your PR merged, please squash commits to a minimum set of meaningful commits.
 
 If you've broken your work up into a set of sequential changes and each commit pass the tests on their own then that's fine. If you've got commits fixing typos or other problems introduced by previous commits in the same PR, then those should be squashed before merging.
 
-If you are new to Git, these links might help:
+=== Tips and links
 
-* https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History
-* http://gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html
+* https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History[Rewriting Git History]
+* http://gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html[Squashing commits with rebase]
+* http://docs.ansible.com/ansible/community.html#community-code-of-conduct[Code of Conduct][[coc]]
+* https://github.com/agis/git-style-guide[Git Style Guide][[gitstyle]]
 
-[coc]:http://docs.ansible.com/ansible/community.html#community-code-of-conduct
-[gitstyle]:https://github.com/agis/git-style-guide
diff --git a/docs/Creating_a_cloud_deployer.adoc b/docs/Creating_a_cloud_deployer.adoc
index e69de29..3229ede 100644
--- a/docs/Creating_a_cloud_deployer.adoc
+++ b/docs/Creating_a_cloud_deployer.adoc
@@ -0,0 +1,4 @@
+
+=== Creating a new Cloud Provider
+
+There are no instructions for this, yet. See the (cloud_providers)[https://github.com/redhat-cop/agnosticd/tree/development/ansible/cloud_providers] directory. 
diff --git a/docs/Creating_a_config.adoc b/docs/Creating_a_config.adoc
index 0d45c57..ada01bc 100644
--- a/docs/Creating_a_config.adoc
+++ b/docs/Creating_a_config.adoc
@@ -1,7 +1,8 @@
 :toc2:
-image::https://travis-ci.org/redhat-cop/agnosticd.svg?branch=development[link="https://travis-ci.org/redhat-cop/agnosticd"]
 
-= Introduction: Writing Configs
+// image::https://travis-ci.org/redhat-cop/agnosticd.svg?branch=development[link="https://travis-ci.org/redhat-cop/agnosticd"]
+
+== Writing Configs
 
 This document gives an overview of the process of writing either a new _config_ 
  from scratch or copying and modifying an existing _config_.
@@ -59,7 +60,7 @@
 * AWS EC2
 * Azure
 
-==== Overview of Ansible Agnostic Deployer Flow
+=== Overview of Ansible Agnostic Deployer Flow
 
 When ansible starts to deploy a _config_ the process involves 2 logically 
  distinct phases, Infrastructure and Software, each broken up into 3 Steps.
@@ -92,7 +93,6 @@
 
 ==== Stage 0 `pre_infra.yml`
 
-
 In this stage *AAD* is the entry playbook and is typical used for setting up
  any infrastructure etc prior to launching a cloud deployment. Typical tasks
   could include:
@@ -101,7 +101,6 @@
 * Moving any ssh keys into place, setting permissions etc
 * Creating any payloads to be used in later stages e.g. repo files etc
 * Ensuring cloud credentials are available 
-
 
 ==== Stage 1 Cloud Provider Deploy
 
@@ -167,7 +166,7 @@
 * User notification of the running configuration 
 
 
-== Overview of a Typical _Config_
+=== Overview of a Typical _Config_
 
 _Configs_ are located in the `ansible/configs/` directory:
 
diff --git a/docs/Creating_an_OpenShift_Workload.adoc b/docs/Creating_an_OpenShift_Workload.adoc
index 502b7b2..b97b447 100644
--- a/docs/Creating_an_OpenShift_Workload.adoc
+++ b/docs/Creating_an_OpenShift_Workload.adoc
@@ -1,6 +1,6 @@
 image::https://travis-ci.org/redhat-cop/agnosticd.svg?branch=development[link="https://travis-ci.org/redhat-cop/agnosticd"]
 
-== What are OpenShift Workloads
+=== OpenShift Workloads
 
 An _OpenShift Workload_ is simply a workload that is applied to an existing, 
  running, OpenShift cluster. For example if you wish to deploy 3Scale, Prometheus,
@@ -14,7 +14,7 @@
 Other OpenShift Workloads  link:../ansible/roles[here.] OpenShift Workloads all begin 
  `ocp-workload-` and follow the traditional structure of an Ansible Role.
 
-== How are _Workloads_ Deployed?
+==== How are _Workloads_ Deployed?
 
 OpenShift _Workloads_ are deployed by applying an Ansible link:https://docs.ansible.com/ansible/latest/user_guide/playbooks_reuse_roles.html[role] to an existing, running, cluster.
 
diff --git a/docs/FAQ.adoc b/docs/FAQ.adoc
index 43b01ae..2da7781 100644
--- a/docs/FAQ.adoc
+++ b/docs/FAQ.adoc
@@ -1,26 +1,26 @@
 :toc2:
 
-== Main
+== FAQ
 
 === Deployment Stages
 
-Q. Can I bypass one or more stages
-A. Yes, `main.yml` tags each stage, use `--skip-tags`
+==== Can I bypass one or more stages?
+Yes, `main.yml` tags each stage, use `--skip-tags`
 
-Q. Where should I store credentails
-A. Never inside the repo. A common pattern is to store them in the home directoy
+==== Where should I store credentails?
+Never inside the repo. A common pattern is to store them in the home directoy
 of the user who executes `ansible-playbook`. For example `~/.ssh` for ssh keys, 
 `~/.aws/credentials` for AWS etc.
 
 ===  Cloud Providers
 
-Q. Can I bypass Stage 1 Cloud Providers completely?
-A. Yes. See `configs/linklight/README` for an example and use `--skip-tags=deploy_infrastructure`
-
+==== Can I bypass Stage 1 Cloud Providers completely?
+Yes. See `configs/linklight/README` for an example and use `--skip-tags=deploy_infrastructure`
 
 === AWS Questions
 
-Q. Can I use AWS Profiles
-A. 
+==== Can I use AWS Profiles?
+
+Maybe...
 
 
diff --git a/docs/Makefile b/docs/Makefile
new file mode 100644
index 0000000..db1987d
--- /dev/null
+++ b/docs/Makefile
@@ -0,0 +1,5 @@
+# This makefile just reduces keystrokes when building the docs locally :-)
+# It is not used by GitHub actions (for that, see .github/workflows).
+
+default:
+	asciidoctor -D . --backend=html5 -o index.html README.adoc
diff --git a/docs/Preparing_your_workstation.adoc b/docs/Preparing_your_workstation.adoc
index 78549af..ab9898e 100644
--- a/docs/Preparing_your_workstation.adoc
+++ b/docs/Preparing_your_workstation.adoc
@@ -1,22 +1,21 @@
+
 :toc2:
 
-= Preparing your Workstation to use the Ansible Playbooks
+== Preparing your Workstation to use Ansible Playbooks
 
-
-
-== Less prerequisites: Dockerfiles
+=== Less prerequisites: Dockerfiles
 
 It is possible to run agnosticd with docker. This way you don't have to install anything (except Docker).
 
 If you want to use docker to deploy, look at the link:../tools/builds[tools/builds] Readme.
 
-== Less prerequistes: python virtualenvs
+=== Less prerequistes: python virtualenvs
 
 It is now encouraged to use python virtualenvs to develop from your laptop.
 
 Please have a look at link:../tools/virtualenvs[tools/virtualenvs].
 
-=== OSP cloud-provider
+==== OSP cloud-provider
 
 .In your home directory
 ----
@@ -45,10 +44,10 @@
 (openstack-ansible-2.9) $ pip install -r https://raw.githubusercontent.com/redhat-cop/agnosticd/development/tools/virtualenvs/openstack-ansible-latest.txt
 ----
 
-== Prerequisites
+=== Prerequisites
 In order to use these playbooks, you will need to set a few things up.
 
-== Software Requirements on workstation
+=== Workstation dependencies
 
 * Some deployments would require a Red Hat Customer Portal account that has
  appropriate subscriptions. This is not required for the playbook themselves.
@@ -56,7 +55,7 @@
 NOTE: Red Hat employee subscriptions can be used
 
 
-=== Software required for deployment
+==== Software required for deployment
 
 * https://www.python.org[Python]
 * http://docs.pythonboto.org[Python Boto] version 2.41 or greater
@@ -131,9 +130,9 @@
 
 ----
 
-== Configuring your workstation
+=== Configuring your workstation
 
-=== Configure the EC2 Credentials
+==== Configure the EC2 Credentials
 
 * You will need to place your EC2 credentials in the ~/.aws/credentials file:
 [source, shell]
@@ -200,7 +199,7 @@
 NOTE: Finer-grained permissions are possible, and pull requests are welcome.
 
 
-=== AWS existing resources
+==== AWS existing resources
 
 * A route53
  link:http://docs.aws.amazon.com/Route53/latest/DeveloperGuide/CreatingHostedZone.html[public hosted zone]
@@ -235,7 +234,7 @@
   done
 ----
 
-== OpenStack
+=== OpenStack
 
 ----
 # Install python modules needed by ansible
@@ -247,7 +246,7 @@
 
 NOTE: on Fedora `dnf install python3-openstacksdk python3-openstackclient python-openstackclient-doc python-openstackclient-lang python3-heatclient python-heatclient-doc python3-dns` will do the job (you may choose to skip doc and lang packages).
 
-=== Azure
+==== Azure
 
 If you want to deploy on azure you will need the Azure client.
 
@@ -284,7 +283,7 @@
 
 NOTE: `--force` is used here, because of a known link:https://github.com/ansible/ansible/issues/38894[issue].
 
-==== Service principal
+===== Service principal
 
 It's better to use a service principal instead of your main credentials. Refer to the https://docs.microsoft.com/en-us/cli/azure/create-an-azure-service-principal-azure-cli?view=azure-cli-latest[official documentation].
 
@@ -305,7 +304,7 @@
 ----
 
 
-=== Virtualenv
+==== Virtualenv
 
 If you want to use virtualenv, you can try & adapt this:
 
diff --git a/docs/README.adoc b/docs/README.adoc
index 5c89d48..53bed3a 100644
--- a/docs/README.adoc
+++ b/docs/README.adoc
@@ -1,21 +1,30 @@
-== Documentation Guide 
+= Agnosticd documentation
+:docinfo: shared
+:doctype: book
+:title: Agnosticd documentation
+:toc: left
+:toclevels: 2
+:sectanchors:
+:sectlinks:
 
+toc::[]
 
-[NOTE]
-====
-Currently, Documents 2018, the documents are being revised and new documents are in the process of being created.
-====
+include::../README.adoc[]
 
+include::Preparing_your_workstation.adoc[]
 
-[source,bash]
-----
-CONTRIBUTING.md
-Creating_a_cloud_deployer.adoc
-Creating_a_config.adoc
-FAQ.adoc
-How_to_use_galaxy_roles_in_your_config.adoc
-Preparing_your_workstation.adoc
-README.adoc
-User_stories.adoc
-----
+include::Contributing.adoc[]
+
+include::Creating_a_config.adoc[]
+include::Creating_an_OpenShift_Workload.adoc[]
+
+== Cloud Providers
+
+include::Supported_Cloud_Providers.adoc[]
+include::Creating_a_cloud_deployer.adoc[]
+
+= Misc
+
+include::FAQ.adoc[FAQ]
+include::User_stories.adoc[User Stories]
 
diff --git a/docs/Supported_Cloud_Providers.adoc b/docs/Supported_Cloud_Providers.adoc
new file mode 100644
index 0000000..bd1c4e2
--- /dev/null
+++ b/docs/Supported_Cloud_Providers.adoc
@@ -0,0 +1,4 @@
+=== Supported Cloud Providers
+
+At the time of writing, Agnosticd can deploy to Azure, AWS and OpenStack. Not
+all configs (workloads) are avaialble on all cloud providers, however.
diff --git a/docs/User_stories.adoc b/docs/User_stories.adoc
index a162523..5e6e543 100644
--- a/docs/User_stories.adoc
+++ b/docs/User_stories.adoc
@@ -1,4 +1,4 @@
-= User Stories for AAD
+== User Stories for AAD
 
 * A new product was acquired by Red Hat and the Architect wants to provide a new product as part of a deployable environment with AAD
 

--
Gitblit v1.9.3