GitHub - IBM/z_ansible_collections_doc: Repository for Z collections documentati...
source link: https://github.com/IBM/z_ansible_collections_doc
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.
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.
ansible-playbook -i inventory site-builder.yml
- 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.
- This will checkout the latest code from every collection included in
the
ansible-playbook -i inventory site-deploy.yml
- 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.
ansible-playbook -i inventory site-uploader.yml --ask-vault-pass
- 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 directorybuild/html
and share that as well.
- Is an optional playbook that when the password is provided, will
upload the documentation generated by the
ansible-playbook -i inventory site-teardown.yml
- 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.
Recommend
-
34
It is a well-known fact that real programmers do not document their code. If it was hard to write, it should be hard to understand and use. But this attitude might prove itself to be a bit problematic if we would...
-
20
Every successful software project I've worked on reaches a point where architectural changes need to be made to ensure the project's continued success. I've been involved in the Drupal community for over a decade, and
-
12
Since collections will be a major new part of every Ansible user's experience in the coming months, I thought I'd write a little about what I consider an Ansible best practice: that is, always using project-relative collec...
-
14
Community General Collection This repository contains the community.general Ansible Collection. The collection is a part of the Ansible package and includes many modules and plugins supported by Ansible community which a...
-
6
Christian Bartels September 30, 2021 1 minute read ...
-
6
SymPy Docs Repository NOTE: The contents of this repository are generated automatically. To make modifications to the SymPy documentation, edit the RST sources in the doc directory of the
-
16
IBM Power Systems AIX Collection Scope The IBM Power Systems AIX collection provides modules that can be used to manage configurations and deployments of Power AIX systems. The collection content helps to incl...
-
6
IBM Cloud DevOps Services - node-nano-doc-updater Click here for more information on IBM Cloud DevOps Services. This is one of hundreds of
-
6
Ansible Z Playbook Repository This repository provides playbooks that can be tailored to automate often repeated IBM Z tasks, links to blogs, and other related media. An
-
9
Sruti Sagaram July 7, 2023 2 minute read
About Joyk
Aggregate valuable and interesting links.
Joyk means Joy of geeK