adriankadev / z_ansible_collections_doc

Repository for Z collections documentation

z_ansible_collections_doc

Repository for Z collections documentation is a repository for all Ansible Z collections which come together under one unified offering. This repository contains the necessary libraries, scripts and playbooks to consume, generate and deploy documentation.

Instructions

Clone the repository, ensure you have all the requirements to allow you to build and generate documentation, see the requirements.txt You can PIP install the requirements into your host but its recommended to use a Python virtual environment (venv).

Optionally, you can use the script (setup.sh) if you are using Mac OS. The script will check the python level, clone the python repository if needed, build and activate a venv, then install all the requirements.

After all requirements are installed, you can run the playbook in the order listed below. Should some changes occure, do not check in .gitmodules, any HTHML or submodules. The repository should be only contain static content, the playbooks will pull the updated collections documentation, submodules and build content each time dynamically.

Of the following playbooks listed below, site-uploader.yml is optional. This playbook will upload generated HTML to webserver for hosting when its easier to share a link instead of creating an archive. This playbook must be run on the same domain the webserver is hosted and you must know the encryption password to access the webserver. The remaining playbooks can be run without any limitations other than if you want to deploy the generated doc, you must have write access to the repository.

Playbook run order

Running the playbooks in this will ensure successful generation and teardown.

1. ansible-playbook -i inventory site-builder.yml
   1. This will checkout the latest code from every collection included in the registry.yml. It will extract and generate HTML documentation, then display it in your local browser. , and if configured and permitted will commit and push the change to Git so it is live. By default, it does not push to Git and it requires permissions.
2. ansible-playbook -i inventory site-deploy.yml
   1. If your user has write access to the repository, this playbook will add, commit and push the changes to branch gh-pages. This playbook will allow you to publish documentation so its live.
3. ansible-playbook -i inventory site-uploader.yml --ask-vault-pass
   1. Is an optional playbook that when the password is provided, will upload the documentation generated by the site-builder.yml playbook to a webserver on the internal private network. The main purpose to use this playbook is if you want to share a link with others to review documentation before making it publicly available. You an always archive the html folder under directory build/html and share that as well.
4. ansible-playbook -i inventory site-teardown.yml
   1. This playbook will restore your local branch back to how it was after it was cloned. It will clean up any generated doc, submodules that were checked out, etc ensuring your environment is clean and ready for future execution.