Publish docs/*.adoc's into into GitHub pages pretty HTML (#1181)

James Read

2020-02-25 eab74b8200fd7af0e496ec3a472c3d7e1a9dbe53

Publish docs/*.adoc's into into GitHub pages pretty HTML (#1181)

* * Initial GitHub Action to publish gh-pages

* This commit will start building from development.

 .github/workflows/asciidoc.yml

New file
@@ -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/

 docs/Contributing.adoc

File was renamed from docs/CONTRIBUTING.md
@@ -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

 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. 

 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:


 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.


 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...



 docs/Makefile

New file
@@ -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

 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:


 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]


 docs/Supported_Cloud_Providers.adoc

New file
@@ -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.

 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