deprecated-2-site-builder.yml

################################################################################
# Copyright (c) IBM Corporation 2020
#
# Description:
#    This playbook will generate documentation for all collections in the
#    registry.yml, perform validation, allow for a preview of generated doc
#    and upload to gh-pages.
#
# Group_vars:
#    Booleans designed to control the flow of this playbook to run this
#    playbook headless. See group_vars/all.yml for more information.
#
#    deploy_to_gh_pages - default is True, it will instruct the playbook to
#       deploy the generated HTML to the doc-site (site/gh-pages).
#
# Usage:
#    ansible-playbook -i inventory site-builder.yml
################################################################################

---
- hosts: all
  gather_facts: no
  connection: local

  # ##############################################################################
  # # Parse 'registry.yml' for certified contributors (key:value)
  # ##############################################################################

  tasks:
    - name: Parse the registry for collection entries
      include_vars: registry.yml

    - name: Display the registered collections and properites in `registry.yml`.
      debug:
         var: collections[item]
      with_items: "{{collections}}"

    ############################################################################
    # Evaluate the state of all collections currently in the repo and compare
    # them to the registry.yml
    #############################################################################

    - name: Evaluate which collections are in directory `source/<collection>`
      stat:
        path: source/{{ item }}
      register: git_submodule
      with_items: "{{collections}}"

    - name: Display the colletions in directory `source/<collection>`
      debug:
        msg: "Collection source/{{item.item}} exists."
      with_items: "{{ git_submodule.results }}"

    ############################################################################
    # Check if there are changes to .gitmodules that are not staged or stashed
    # that will result in this playbook failing to properly teardown then init
    # based on the registry.yml.
    # Avoids this error:
    #  fatal: Please, stage your changes to .gitmodules or stash them to proceed
    ############################################################################

    - name: Check status of `.gitmodules`.
      shell: |
        git status --untracked-files=no --porcelain .gitmodules
      register: status_gitmodules

    - name: Display status of `.gitmodules`.
      debug: msg="{{status_gitmodules}}"

    - name: Evaluate if `.gitmodules` has unstaged changes.
      set_fact:
        status_gitmodule_M: "{{ status_gitmodules.stdout | regex_search('^\\s*M ')}}"

    - name: Display if `.gitmodules` has unstaged changes
      debug:
        msg: "Unstaged changes have been found in .gitsubmodules."
      when: status_gitmodule_M

    # If you modify a file, then:
    #  (A) use git add to copy it to the index / staging-area
    #  (B) modify it again, now all three versions of that file differ.
    #  This is will generate the MM status.
    - name: Evaluate if `.gitmodules` has staged and unstaged changes.
      set_fact:
        status_gitmodule_MM: "{{ status_gitmodules.stdout | regex_search('^\\s*MM ')}}"

    - name: Display if `.gitmodules` has staged and unstaged changes.
      debug:
        msg: "Staged and unstaged changes have been found in .gitsubmodules."
      when: status_gitmodule_MM

    - name: Reset .gitmodules if there are staged and unstaged changes.
      shell: |
        git reset HEAD .gitmodules
      when: status_gitmodule_MM

    - name: Stagging .gitmodules
      shell: |
        git add .gitmodules
      register: add_gitmodules
      when: status_gitmodule_M or status_gitmodule_MM

    - name: Display result from staging .gitmodules.
      debug: msg="{{add_gitmodules}}"
      when: status_gitmodule_M or status_gitmodule_MM

    - name: Display summary of changes.
      debug: msg="Changes have been detected for '.gitmodules', changes have been
        staged, you may unstage them with command 'git reset HEAD .gitmodules'"
      when: status_gitmodule_M or status_gitmodule_MM

    # ############################################################################
    # Complete teardown and setup of all submodules to avoid conflicts when new
    # private branches are added to the registry.yml and not properly udated in
    # the .gitmodules config; just makes for a cleaner run and less troubleshooting
    # for those who don't properly maintain their clone repository
    #
    # NOTE: This only manages the submodules in the `registry.yml` not any
    # submodules excluded from the registry.yml
    # ############################################################################

    # NOTE: Performing this as a single task introduces failures that can not be ignored.
    #       Thus it has been reduced to individual tasks.
    # - name: Teardown all submodules then init them according to `registry.yml`.
    #   shell: |
    #     git rm -f --cached source/{{ item }}
    #     rm -rf source/{{ item }}
    #     rm -rf .git/modules/source/{{ item }}
    #     git config -f .gitmodules --remove-section submodule.source/{{ item }}
    #     git submodule add {{ collections[item].git}} source/{{ item }}
    #     git submodule init
    #   with_items: "{{collections}}"
    #   register: git_add_submodules
    # - name: Display the result from the teardown and init for all submodules registerd in `registry.yml`.
    #   debug: msg="{{ git_add_submodules }}"
    #   when: git_add_submodules

    - name: 1 - Remove cached submodules according to `registry.yml`.
      shell: |
        git rm -f --cached source/{{ item }}
      with_items: "{{collections}}"
      register: git_add_submodules_1
      ignore_errors: yes

    - name: 1 - Display Remove cached submodules according to `registry.yml`.
      debug: msg="{{ git_add_submodules_1 }}"
      when: git_add_submodules_1

    - name: 2 - Remove local files according to `registry.yml`.
      shell: |
        rm -rf source/{{ item }}
      with_items: "{{collections}}"
      register: git_add_submodules_2

    - name: 2 - Display remove local files according to `registry.yml`.
      debug: msg="{{ git_add_submodules_2 }}"
      when: git_add_submodules_2

    - name: 3 - Remove all git managed submodule content according to `registry.yml`.
      shell: |
        rm -rf .git/modules/source/{{ item }}
      with_items: "{{collections}}"
      register: git_add_submodules_3

    - name: 3 - Display remove all git managed submodule content according to `registry.yml`.
      debug: msg="{{ git_add_submodules_3 }}"
      when: git_add_submodules_3

    - name: 4 - Remove .gitmodules references for all submodules according to `registry.yml`.
      shell: |
        git config -f .gitmodules --remove-section submodule.source/{{ item }}
      with_items: "{{collections}}"
      register: git_add_submodules_4
      ignore_errors: yes

    - name: 4 - Display remove .gitmodules references for all submodules according to `registry.yml`.
      debug: msg="{{ git_add_submodules_4 }}"
      when: git_add_submodules_4

    - name: 5 - Add all submodules to .gitmodules according to `registry.yml`.
      shell: |
        git submodule add {{ collections[item].git}} source/{{ item }}
      with_items: "{{collections}}"
      register: git_add_submodules_5

    - name: 5 - Display add all submodules to .gitmodules according to `registry.yml`.
      debug: msg="{{ git_add_submodules_5 }}"
      when: git_add_submodules_5

    - name: 6 - Init all submodules according to `registry.yml`.
      shell: |
        git submodule init
      with_items: "{{collections}}"
      register: git_add_submodules_6

    - name: 6 - Init all submodules according to `registry.yml`.
      debug: msg="{{ git_add_submodules_6 }}"
      when: git_add_submodules_6

    # # ############################################################################
    # # After teardown and init, traverse each submodule and checkout the latest
    # # branch indentified in registry.yml
    # # ############################################################################

    - name: Update each of the submodule contents under `source/<submodule>`.
      shell: |
          cd source/{{ item }}
          git fetch --all
          git reset --hard origin/{{ collections[item].origin }}
          git checkout {{ collections[item].latest }}
          git pull origin {{ collections[item].latest }}
      with_items: "{{collections}}"
      register: git_checkout_latest

    - name: Display the results after updating the submodules under `source/<submodule>`.
      debug: msg="{{ git_checkout_latest }}"

    ############################################################################
    # Generate and view HTML
    ############################################################################

    - name: Generate HTML and display the results locally in the users browser
      raw: make clean; make html; make view-html;

# ############################################################################
# Deploy HTML to gh-pages if deploy_to_gh_pages=True
# Must have WRITE access to the repository.
# ############################################################################
#
# This content has been pulled into another playbook; site-deploy.yml
#    - meta: end_play
#      when: not deploy_to_gh_pages
#
#    - name: Copy the generated HTML from `build/html/` to `site/gh-pages/`
#      shell: |
#          cd site/gh-pages
#          git checkout gh-pages
#          cp -R ../../build/html/* .
#          git add .
#          git status
#          git commit -m "Automated commit to update documentation"
#          git push -f
#          cd ../..
#          git checkout master
#          git status
#          git submodule update
#      register: git_update_doc
#      when: deploy_to_gh_pages
#
#    - name: Display the HTML content uploaded to the doc site (gh-pages)
#      debug: msg="{{ git_update_doc }}"
#      when: deploy_to_gh_pages

################################################################################
# It does not look like we need to perform this check anymore and in fact
# it appears this is committing the submodules I was seeing, I am usure why
# I introduced this logic, possibly before the teardown scripts.
# Note, at this point playbook if the gh-pages has been commited this will be
# left behind "modified:   site/gh-pages (new commits)" after a teardown
# git submodule update will fix this
################################################################################
#    - name: Check status of `site/gh-pages`.
#      shell: |
#        git status --untracked-files=no --porcelain site/gh-pages
#      register: status_site_gh_pages
#
#    - name: Display status of `site/gh-pages`.
#      debug: msg="{{status_site_gh_pages}}"
#      when: status_site_gh_pages
#
#    - name: Evaluate if `site/gh-pages` has unstaged changes.
#      set_fact:
#        status_site_gh_pages_M: "{{ status_site_gh_pages.stdout | regex_search('^\\s*M ')}}"
#      when: status_site_gh_pages
#
#    - name: Display if `site/gh-pages` has unstaged changes
#      debug:
#        msg: "Unstaged changes have been found in site/gh-pages."
#      when: status_site_gh_pages
#
#    - name: Commiting and pushing unstaged changes for `site/gh-pages`.
#      shell: |
#        git add site/gh-pages
#        git commit -m "Automated commit to update subproject commit."
#        git push -f
#      register: status_commit_site_pages_push
#
#    - name: Display commiting and pushing unstaged changes for `site/gh-pages`.
#      debug: msg="{{status_commit_site_pages_push}}"
#      when: status_commit_site_pages_push

################################################################################
# If the content has been built and pushed to gh-pages, display the URL to the
# user
################################################################################
#    # See https://ibm.github.io/z_ansible_collections_doc/index.html
#    - name: Follow this URL to view the updated collection content
#      debug: msg="https://ibm.github.io/z_ansible_collections_doc/index.html"
#      when: deploy_to_gh_pages