Journey of the development of Ansible Collection? (Part 4)
Let’s continue from the last part :), please do a quick recap if you forgot something about the journey :D.
Let’s explorer behind the scene stuff for automatic documentation creation for Ansible Collection.
December 2020
Have you noticed that all the Ansible modules have a lot of components in the code itself like
Example Module: aws_amp.py
After Running the Documentation Tool, we get documentation like this
community.missing_collection.aws_amp_module.rst which far easier to read than actually reading the code.
Ansible Core Team had created a documentation tool that is/was generating documentation out of these values automatically whenever they were releasing a new version of Ansible.
Unfortunately, there is no documentation for this tool/process So I had to talk with a couple of persons from the Ansible Community to find out the process and respective tool.
A lot of Ansible Community Teammates pointed to me right direction but still, I had to make that tool working with my collection that was quite interesting as well.
After reading a bit more about the tool and its working, I realized that a couple of things has to be updated in my collection to make it work.
Readme.md should be renamed to README.md and it has to be the same otherwise the tool won’t be able to update the readme which is required because we will have the documentation but no one knows where to look for them.
README.md should following sections as well
- Ansible Version Section
<!--start requires_ansible-->
should be empty here, it will be auto updated by tool.
<!--end requires_ansible-->- Docs Index Section
<!--start collection content-->
should be empty here, it will be auto updated by tool.
<!--end collection content-->Now, let’s install the documentation tool
$ pip3 install git+https://github.com/ansible-network/collection_prep.gitNote: Please do update your galaxy.yml
Sample Run to Create Documentation
$ collection_prep_add_docs -p . -b master
INFO Setting collection name to community.missing_collection
INFO Setting GitHub repository url to https://github.com/116davinder/ansible.missing_collection
INFO Purging content from directory /home/dpal/python-projects/ansible.missing_collection/docs
INFO Making docs directory /home/dpal/python-projects/ansible.missing_collection/docs
INFO Process content in /home/dpal/python-projects/ansible.missing_collection/plugins/modules
INFO Processing /home/dpal/python-projects/ansible.missing_collection/plugins/modules/aws_amp_info.py
..............Once you are done, you will see several files (*.rst) in the docs folder. Review One of the files and at last push them to your collection repository.
Few Extra Tips
If collection_prep_add_docs fails then you can check the followings things
1. Make sure galaxy.yml is correctly YAML formatted and all the fields are defined as I have defined in my collection.
2.Make sure all module documentation sections like DOCUMENTATION, EXAMPLES, and RETURN are YAML formatted.
3. Still are unable to resolve than remove all the documentation sections from the module and add them one at a time and run the tool to see where is the problem. With my experience, I have spent most of my time resolving problems related to YAML formatting.
Have Fun!, Hopefully, I will be able to write the next part of it very soon as well that is related to module utils in Ansible Collection.
