deprecated-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,
#    upload it to a local Apache server for review 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.
#
#    accept_new_registry_collections - Default is True, it will instruct the
#       playbook to Git pull in any collections repositories that are not
#       currently in this repository that appear in the `registry.yml`
#    deploy_to_web_server - Default is True, it deploys the HTML to a LAN Apache
#       server so the doc can be shared via a link for others to review before
#       deploying live.
#    deploy_to_gh_pages - default is True, it will instruct the playbook to
#       deploy the generated HTML to the doc-site (site/gh-pages).
#    cleanup_generated_html - default is True, it will remove all generated
#      HTML to avoid checking that in, this repo should not store generated HTML
#
# Usage:
#    ansible-playbook -i inventory site-builder.yaml
#    ansible-playbook -i inventory site-builder.yml --ask-vault-pass
################################################################################

---
- hosts: all
  gather_facts: no
  connection: local
  vars:
    ############################################################################
    # Configure variables as needed in inventory
    ############################################################################

    # Array of collection git submodules located under directory source/<...>
    ARRAY_OF_REGISTERED_COLLECTIONS: []

    # Array of collections in registry but NOT under directory source/<...>
    # in other words, collections pending acceptance
    ARRAY_OF_UNREGISTERED_COLLECTIONS: []

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

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

    - name: Display the registry collection entry details
      debug:
        msg: "Collection = {{ item.key }}, git = {{ item.value.git }}, stable = {{ item.value.stable }}, latest = {{ item.value.latest }}"
      loop: "{{ lookup('dict', collections) }}"

    - name: Display the registry collection entriy names
      debug:
         var: collections[item]
          # Display the git url for the collection
          # var: collections[item].git
          # msg: "{{item}}"
      with_items: "{{collections}}"

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

    - name: Evaluate which colletions 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="{{ git_submodule }}"

    - name: Populate array with the unregistered collections (collections in registry.yml but not in this repo)
      set_fact:
        ARRAY_OF_UNREGISTERED_COLLECTIONS="{{ ARRAY_OF_UNREGISTERED_COLLECTIONS }} + [ '{{ item.item}}' ]"
      with_items: "{{ git_submodule.results}}"
      when: not item.stat.exists

    - name: Display the unregistered collections
      debug: msg="{{ ARRAY_OF_UNREGISTERED_COLLECTIONS }}"

      # If we encounter a collection under source/<collection> that is empty,
      # then correctly restore the Git submodule
    - name: Evaluate if the collections under `source/<collection>` have files
      shell: |
          find source/{{ item.item }}/ -type f -print | wc -l
      with_items: "{{ git_submodule.results}}"
      register: collection_file_count
      when: item.stat.exists

    - name: Display the collections under `source/<collection>` that have NO files
      debug: msg="{{ item }}"
      with_items: "{{ collection_file_count.results }}"
      when: item.item.stat.exists and item.stdout|int == 0

    - name: Update the collections that have no files under under `source/<collection>`
      shell: |
          git rm -f --cached source/{{ item.item.item }}
          rm -rf .git/modules/source/{{ item.item.item }}
          git config -f .gitmodules --remove-section submodule.source/{{ item.item.item }}
          rm -rf source/{{ item.item.item }}
          git submodule add git@github.com:ansible-collections/{{ item.item.item }}.git source/{{ item.item.item }}
          git submodule init
      with_items: "{{ collection_file_count.results }}"
      when: item.item.stat.exists and item.stdout|int == 0

      # These commands can get the latest Git tag if you want to automate the getting the latest tag
      #   cd source/{{ item }}
      #   git fetch --tags
      #   tag=$(git describe --tags `git rev-list --tags --max-count=1`)
      #   git checkout $tag
      #   cd ../..
    - name: Add the unregistered collections if we are accepting new collections
      shell: |
          touch .gitmodules
          git submodule add git@github.com:ansible-collections/{{ item }}.git source/{{ item }}
          git submodule init
      with_items: "{{ ARRAY_OF_UNREGISTERED_COLLECTIONS }}"
      register: git_add_submodules
      when: accept_new_registry_collections

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

    - name: Display the updated collections under the `source/<collection>` directory
      debug: msg="{{ git_submodule }}"

    - name: Populate an array with the registered collections found under the `source/<collection>` directory
      set_fact:
        ARRAY_OF_REGISTERED_COLLECTIONS="{{ ARRAY_OF_REGISTERED_COLLECTIONS }} + [ '{{ item.item }}' ]"
      with_items: "{{ git_submodule.results}}"
      when: item.stat.exists

    - name: Display the array of registered collections in this repository
      debug: msg="{{ ARRAY_OF_REGISTERED_COLLECTIONS }}"

    ############################################################################
    # Git checkout the correct branch based on the registry.yml values, then
    # git pull the latest changes
    # TODO:
    #   Consider defaulting to the latest branch (see above ), tag=$(git describe --tags `git rev-list --tags --max-count=1`)
    #   Consider checking them out as 'latest' and 'stable', ie `git checkout v1.1.0-beta1 -b latest`
    ############################################################################

    - name: Update the collections contents with Git for collections under `source/<collection>`
      shell: |
          cd source/{{ item.key }}
          git fetch --all
          git checkout {{ item.value.latest }}
          git reset --hard origin/master
          git pull origin {{ item.value.latest }}
      loop: "{{ lookup('dict', collections) }}"
      register: git_checkout_latest
      when: item.key in ARRAY_OF_REGISTERED_COLLECTIONS

    - name: Display the results to updating the collections under `source/<collection>`
      debug: msg="{{ git_checkout_latest }}"

    # Enable  this for version support , needs to have its own array for stable
    # - name: Git checkout the stable branch or tag provided in the registry
    #   shell: |
    #       cd source/{{ item.key }}
    #       git checkout {{ item.value.stable }}
    #       git pull origin {{ item.value.stable }}
    #   loop: "{{ lookup('dict', collections) }}"
    #   register: git_checkout_stable
    #   when: item.key in ARRAY_OF_REGISTERED_COLLECTIONS
    #   ignore_errors: yes
    #
    # - name: Display Git stable checkout
    #   debug: msg="{{ git_checkout_stable }}"
    #   when: git_checkout_stable

    ############################################################################
    # Update all collections (git submodules) - this is now done above by
    # traversing each collection and doing a git pull origin <collection>
    # Commands that DON'T work for this are:
    #   - git submodule foreach git pull origin master
    #   - git submodule update --recursive --remote
    # - name: Git update all registered collections in this repository
    #   shell: |
    #       git submodule update --recursive --remote
    # ##########################################################################

    ############################################################################
    # Evaluate that the collections (git submodules) have required files
    ############################################################################

    ### - name: Check that each collection has a source/<collection>/docs/zos-collection-index.rst file
    ###   stat:
    ###     path: source/{{ item }}/docs/zos-collection-index.rst
    ###   register: stat_collection_index_rst
    ###   with_items: "{{ ARRAY_OF_REGISTERED_COLLECTIONS }}"
### 
    ### - name: Display the collections with file source/<collection>/docs/zos-collection-index.rst
    ###   debug: msg="{{ item.item }}"
    ###   with_items: "{{ stat_collection_index_rst.results}}"
    ###   when: item.stat.exists
### 
    ###   # Fail the build if collections don't meet requirements
    ### - name: Determine which collections are valid and continue, otherwise exit the build
    ###   assert:
    ###     that:
    ###       - item.stat.exists
    ###     success_msg: "[PASS] Collection {{ item.item }} contains source/{{ item.item }}/docszos-collection-index.rst"
    ###     fail_msg: "[FAIL] Collection {{ item.item }} does NOT contain source/{{ item.item }}/docszos-collection-index.rst"
    ###   with_items: "{{ stat_collection_index_rst.results}}"
### 
    # ############################################################################
    # # 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 web-server for review if deploy_to_web_server=True
    # ############################################################################

      # This is a manual prompt to continue which would need to be removed when this is automated
    - name: Confirm continuing to upload HTML to private Apache server
      pause:
        prompt: "Do you want to upload the generated HTML to an Apache server for review? (yes/no)"
      register: confirm_delete
      when: deploy_to_web_server | bool

    - raw: make clean;
      when: deploy_to_web_server | bool and not confirm_delete.user_input | bool


    - meta: end_play
      when: deploy_to_web_server | bool and not confirm_delete.user_input | bool

    - name: Copying files to an Apache server for review
      copy:
        src: build/html/index.html
        dest: /var/www/collection-doc
        owner: root
        group: root
        mode: 0755
        force: yes
      vars:
        ansible_become_password: "{{ webserver_password }}"
      delegate_to: "{{ web_server }}"
      remote_user: "{{ webserver_user }}"
      register: webserver_upload
      when: deploy_to_web_server | bool

    - name: Uploaded content for review
      debug: msg="Successfully uploaded content for review at [ http://collection-doc.{{ web_server }}/index.html ]"
      when: deploy_to_web_server | bool and webserver_upload and not webserver_upload.failed

    # ############################################################################
    # # Deploy HTML to gh-pages if deploy_to_gh_pages=True
    # ############################################################################

    # TODO: 
    # This should not run as part of the playbook, tbh not sure why/where to run this but
    # if anything it should part of an init and not post init as it wipes out the entire existance
    # of the gh-pages submodule and .gitmodules entry.
    # - name: Update the 'site/gh-pages' after a repository clone so its tracked accordingly
    #   shell: |
    #       git rm --cached site/gh-pages
    #       rm -rf .git/modules/site/*
    #       git config -f .gitmodules --remove-section submodule.site/gh-pages
    #       rm -rf site/gh-pages
    #       git submodule add -b -f gh-pages git@github.com:IBM/z_ansible_collections_doc.git site/gh-pages
    #       git submodule init
    #   register: site_gh_pages_return
    # - name: Display the Git submodule 'site/gh-pages' result
    #   debug: msg="{{ site_gh_pages_return }}"
    #   when: site_gh_pages_return

    - name: Confirm continuing to upload HTML to public doc-site (gh-pages)
      pause:
        prompt: "Do you want to upload the generated HTML to the doc-site and go live ? (yes/no)"
      register: confirm_delete

    - raw: make clean;
      when: not confirm_delete.user_input | bool

    - meta: end_play
      when: not confirm_delete.user_input | bool

    - 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
          # cp -R build/html/* site/gh-pages
          # cd site/gh-pages
          # git checkout gh-pages
          # git add .
          # git status
          # git commit -m "Automated commit to update documentation"
          # git push -f
          # cd ../..
          # git checkout master
      register: git_update_doc
      when: deploy_to_gh_pages

    # See https://ibm.github.io/z_ansible_collections_doc/index.html
    - name: Display the HTML content uploaded to the doc site (gh-pages)
      debug: msg="{{ git_update_doc }}"
      when: deploy_to_gh_pages

    - raw: make clean;
      when: not confirm_delete.user_input | bool

    ############################################################################
    # Tear down, remove anything we don't need or want and reset the environment
    ############################################################################
    - name: Tear down - remove directory `build/`
      file:
        path: build
        state: absent

    # Consider for tear down to remove any submodule contents in gh-pages
    # - name: return motd to registered var
    #   command: git clean -fd site/gh-pages/

    # Hack of a solution for now, got to be better ways and to find those need
    # to make time for them.
    - name: Tear down - clean up git submodule `source/ibm_zos_core/`
      command: git submodule update source/ibm_zos_core/

    - name: Tear down - clean up git submodule `source/ibm_zos_ims/`
      command: git submodule update source/ibm_zos_ims/

    - name: Tear down - clean up git submodule `site/gh-pages`
      command: git submodule update site/gh-pages

    # TODO: Test this on the next deployment
    # - name: Display site/gh-pages updated HTML content
    #   debug: msg="Successfully committed documentation to site/gh-pages viewable at [ https://ibm.github.io/z_ansible_collections_doc/index.html ]"
    #   when: git_update_doc.false and (stdout_lines | join('') | search('Automated commit'))
    #   stdout_lines

    ############################################################################
    # Notes on how to add gh-pages as a submodule. This is has been done prior
    # running this build script. Its part of the initial repository build.
    ############################################################################
    # git checkout --orphan gh-pages
    # git reset --hard
    # git commit --allow-empty -m "Init"
    # git checkout master
    # git push -u origin gh-pages
    # git submodule add -b gh-pages git@github.com:IBM/z_ansible_collections_doc.git site/gh-pages