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.
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.
Running the playbooks in this will ensure successful generation and teardown.
ansible-playbook -i inventory site-builder.yml
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.ansible-playbook -i inventory site-deploy.yml
ansible-playbook -i inventory site-uploader.yml --ask-vault-pass
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.ansible-playbook -i inventory site-teardown.yml