initialise repo

.github/workflows/make_docs.yml

@@ -0,0 +1,43 @@
+name: publish document
+
+on:
+  push:
+    branches:
+      - devel
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+    container: fedora:latest
+
+    steps:
+    - name: Install requirements
+      run: sudo dnf install -y git graphviz make plantuml rubygem-asciidoctor rubygem-asciidoctor-pdf rubygem-rouge
+
+    - name: Repository checkout
+      uses: actions/checkout@v3
+
+    - name: Move to the correct folder
+      run: cd $GITHUB_WORKSPACE
+
+    - name: Ensure git folder is considered safe
+      run: git config --global --add safe.directory "$GITHUB_WORKSPACE"
+
+    - name: Render HTML
+      run: make release
+
+    - name: Git add and force push to docs
+      run: git add -f docs
+
+    - name: Push changes
+      uses: stefanzweifel/git-auto-commit-action@v4
+      with:
+        commit_message: publish release
+        file_pattern: docs/*
+        add_options: '-A --force'
+        branch: docs  # main branch is protected, make sure this one is used for GitHub pages
+        # the following options are necessary to forcefully overwrite each time the branch
+        skip_fetch: true
+        skip_checkout: true
+        push_options: '--force'

.github/workflows/make_preview_docs.yml

@@ -0,0 +1,33 @@
+name: create preview renders
+
+on:
+  push:
+    branches:
+      - '!devel'
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Install requirements
+      run: sudo apt-get install asciidoctor ruby-asciidoctor-pdf
+
+    - name: Install requirements
+      run: cd $GITHUB_WORKSPACE
+
+    - name: render preview
+      run: make preview
+
+    - uses: actions/upload-artifact@v3
+      with:
+        name: preview-pdf
+        path: docs/preview/*.pdf
+
+    - uses: actions/upload-artifact@v3
+      with:
+        name: preview-html
+        path: docs/preview/*.html

.github/workflows/test_docs.yml

@@ -0,0 +1,26 @@
+name: test document generation
+
+on:
+  pull_request:
+
+jobs:
+  test-build-docs:
+
+    runs-on: ubuntu-latest
+    container: fedora:latest
+
+    steps:
+    - name: Install requirements
+      run: sudo dnf install -y git graphviz make plantuml rubygem-asciidoctor rubygem-asciidoctor-pdf rubygem-rouge
+
+    - name: Repository checkout
+      uses: actions/checkout@v3
+
+    - name: Move to the correct folder
+      run: cd $GITHUB_WORKSPACE
+
+    - name: Ensure git folder is considered safe
+      run: git config --global --add safe.directory "$GITHUB_WORKSPACE"
+
+    - name: Render HTML
+      run: make release

.github/workflows/test_markdown_links.yml

@@ -0,0 +1,21 @@
+---
+# This action checks all Markdown files in the repository for broken links. 
+# (Uses https://github.com/tcort/markdown-link-check) 
+name: markdown link check
+
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  markdown-link-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: gaurav-nelson/github-action-markdown-link-check@v1
+        with:
+          use-quiet-mode: 'yes'
+          use-verbose-mode: 'yes'
+          config-file: '.mlc_config.json'
+...

.gitignore

@@ -0,0 +1,16 @@
+# generated files
+*.html
+*.pdf
+*.png
+*.svg
+docs
+
+# temporary files
+.*.swp
+*~
+
+# my own files, only for local usage
+*[_.]myown[_.]*
+
+# misc
+.vscode

CONTRIBUTE.adoc

@@ -0,0 +1,144 @@
+= Contribution guidelines
+include::_style/render.adoc[]
+
+Before you suggest _automation_ guidelines, please consider the _contribution_ guidelines layed out in this document.
+
+== Writing
+
+. The guidelines are written in https://asciidoctor.org[asciidoc as described by Asciidoctor].
+. each guideline is made of one sentence, as easy to remember as possible, followed by a collapsible description, made of:
+** explanations
+** rationale
+** examples
++
+The result looks then as the following template shows (you may copy & paste):
++
+[source,asciidoc]
+------------------------------------------------------------------------
+== Do this and do not do that is the guideline
+[%collapsible]
+====
+Explanations:: These are explanations
+
+Rationale:: This is the rationale
+
+Examples:: These are examples
++
+.A mini playbook example
+[source,yaml]
+----
+- name: a mini example of playbook
+  hosts: all
+  gather_facts: false
+  become: false
+
+  tasks:
+
+  - name: say what we all think
+    debug:
+      msg: asciidoctor is {{ my_private_thoughts }}
+----
++
+Even more examples...
+====
+------------------------------------------------------------------------
+// maintain the code above in sync with the example below
++
+NOTE: see how it looks like in the <<_example>> section below.
++
+. Those guidelines are grouped into sections and optionally sub-sections, as far as required for maintainability.
+. Those (sub-)sections can be written in their own source file, but then are included with `include::directory/file.adoc[leveloffset=1]` in the parent section's file.
+  This makes sure that all source files are interlinked and can be rendered all together by rendering the top `README.adoc`, either with `asciidoctor` or with `asciidoctor-pdf`.
++
+NOTE: this contribution file is obviously not meant for inclusion in the overall document.
++
+. Each source file has a single title (the line starting with one equal sign) and can be rendered individually (the `leveloffset` is set such that it fits in the overall headings structure when included).
+. The source code is written as readable as possible in its raw form, without impacting maintainability.
+. We follow the https://asciidoctor.org/docs/asciidoc-recommended-practices/[Asciidoc recommended practices].
+. Sentences are written in the present tense form, avoid "should", "must", etc.
+  For example, "Sentences are written", not "Sentences should be written" or "Sentences must be written". This avoids filler words.
+. The https://en.wikipedia.org/wiki/Singular_they[singular "they"] is used to avoid the unreadable "he/she/it" construct and still be neutral.
+
+== Contributing
+
+. Just fork the repository, create a Pull Request (PR) and offer your changes.
++
+TIP: limiting each PR to a single recommendation makes it easier to review.
+This furthermore speeds up approval, which is an advantage also for contributors.
+
+. Feel free to review existing PR and give your opinion
+. Also an issue against one of the recommendations is a valid approach
+
+== Example
+
+This is how one guideline as shown above looks like once rendered:
+
+// This is a duplicate from the above code, but rendered e.g. by GitHub, it shows how it's supposed to look like.
+
+=== Do this and do not do that is the guideline
+[%collapsible]
+====
+Explanations:: These are explanations
+
+Rationale:: This is the rationale
+
+Examples:: These are examples
++
+.A mini playbook example
+[source,yaml]
+----
+- name: a mini example of playbook
+  hosts: all
+  gather_facts: false
+  become: false
+
+  tasks:
+
+  - name: say what we all think
+    debug:
+      msg: asciidoctor is {{ my_private_thoughts }}
+----
++
+Even more examples...
+====
+
+== Publish for the website
+
+Use for now the following manual command to publish to
+link:++https://redhat-cop.github.io/aap_config_as_code_docs/++[the website]:
+
+[source,bash]
+----
+asciidoctor -a toc=left -D docs -o index.html README.adoc
+asciidoctor -a toc=left -D docs CONTRIBUTE.adoc
+mkdir -p docs/images
+cp -v images/*.svg docs/images
+----
+
+NOTE: it doesn't seem that there is any much better way to keep links to images correct according to the https://docs.asciidoctor.org/asciidoctor/latest/html-backend/manage-images/[HTML generation / managed images] chapter.
+
+== Creating a PDF
+
+If you run (a current) Fedora Linux,
+then you can use the `Makefile`.
+
+* `make view` generates both PDF files and displays the GPA guide
+* `make print` prints to your default printer
+* `make spell` runs hunspell for spellchecking
+* …
+
+Alternatively, use the following manual commands to generate the 2 PDFs:
+
+[source,bash]
+----
+asciidoctor-pdf \
+  --attribute=gitdate=$(git log -1 --date=short --pretty=format:%cd) \
+  --attribute=githash=$(git rev-parse --verify HEAD) \
+  --out-file Good_Practices_for_Ansible.pdf \
+  README.adoc
+asciidoctor-pdf \
+  --attribute=gitdate=$(git log -1 --date=short --pretty=format:%cd) \
+  --attribute=githash=$(git rev-parse --verify HEAD) \
+  --out-file Contributing-to-GPA.pdf \
+  CONTRIBUTE.adoc
+----

Makefile

@@ -0,0 +1,73 @@
+# be sure to have the following RPMs installed on Fedora Linux
+#
+# okular
+# asciidoctor-pdf
+# rubygem-rugged
+# hunspell
+# hunspell-en-GB
+# rubygem-ffi ?
+# rubygem-json ?
+
+ADOCPDF = asciidoctor-pdf --attribute=gitdate=$(shell git log -1 --date=short --pretty=format:%cd) --attribute=githash=$(shell git rev-parse --verify HEAD) --failure-level=warn
+ADOCHTML = asciidoctor -a toc=left --attribute=gitdate=$(shell git log -1 --date=short --pretty=format:%cd) --attribute=githash=$(shell git rev-parse --verify HEAD) --failure-level=warn
+ACROREAD = okular
+VCS = git
+INFILE = README.adoc
+INFILE2 = CONTRIBUTE.adoc
+OUTFILE = aap_config_as_code
+OUTFILE2 = Contributing-to-aap_cac
+PRINT = lpr
+SPELL = hunspell
+SPELLOPTS = -d en_GB
+
+all: $(OUTFILE)
+
+$(OUTFILE): $(INFILE) *.adoc */*.adoc _images/* Makefile .git/index
+	$(ADOCPDF) --out-file $(OUTFILE).pdf $(INFILE)
+	$(ADOCPDF) --out-file $(OUTFILE2).pdf $(INFILE2)
+
+view: viewpdf
+
+print: $(OUTFILE)
+	$(PRINT) $(OUTFILE).pdf
+
+viewpdf: $(OUTFILE)
+	$(ACROREAD) $(OUTFILE).pdf
+
+clean:
+	rm -f $(OUTFILE).pdf
+	rm -f $(OUTFILE2).pdf
+	rm -rf .AppleDouble
+
+spell:
+	$(SPELL) $(SPELLOPTS) *.adoc */*.adoc
+
+commit: clean
+	$(VCS) commit .
+
+push: clean
+	$(VCS) push
+
+pull:
+	$(VCS) pull
+
+plantuml:
+	for f in images/*.plantuml; do \
+		plantuml $${f} -tsvg; \
+	done
+
+release: plantuml
+	mkdir -p docs
+	$(ADOCHTML) -D docs --out-file index.html $(INFILE)
+	$(ADOCHTML) -D docs --out-file CONTRIBUTE.html $(INFILE2)
+	mkdir -p docs/images
+	cp -v images/*.svg docs/images
+
+preview:
+	mkdir -p docs
+	$(ADOCPDF) --out-file docs/preview/$(OUTFILE).pdf $(INFILE)
+	$(ADOCPDF) --out-file docs/preview/$(OUTFILE2).pdf $(INFILE2)
+	$(ADOCHTML) --out-file docs/preview/$(OUTFILE).html $(INFILE)
+	$(ADOCHTML) --out-file docs/preview/$(OUTFILE2).html $(INFILE2)
+	mkdir -p docs/preview/images
+	cp -v images/*.svg docs/preview/images

README.adoc

@@ -0,0 +1,12 @@
+= Ansible Automation Platform Configuration as Code Collections
+include::_style/render.adoc[]
+
+== Introduction
+
+Several collections have been created by the Red Hat Communities of Practice to assist with configuring aspects of the Ansible Automation Platform (AAP) using configuration as code practices. This site will guide you through these collections, the use cases, how to use and strategies for scaling appropriately.
+
+=== Where to get and maintain this document
+
+This document is published to https://redhat-cop.github.io/aap_config_as_code_docs/, it is open source and its source code is maintained at https://github.com/redhat-cop/aap_config_as_code_docs/.
+
+include::collections/README.adoc[leveloffset=1]