CODEWITHSUNDEEP
ansibledocumentation
Felixkruemel
Felixkruemel

Reputation: 514

How to generate a documentation from ansible-modules

We are developing an ansible collection using ansible modules like openstack does: https://github.com/openstack/ansible-collections-openstack

How can I generate docs from the modules like the ansible wiki has it? https://docs.ansible.com/ansible/2.8/modules/os_auth_module.html#os-auth-module

I found this on the internet but I can't get antsibull to work https://www.die-welt.net/2020/07/building-documentation-for-ansible-collections-using-antsibull/ The problem there is that despite of having the ANSIBLE_COLLECTIONS_PATH env var set it will just output an nearly empty file with antsibull-docs collection --use-current --dest-dir ~/docs collectionname

Also I don't know whether this is the right way to do that.

So what can I do?

Upvotes: 1

Views: 3347

Answers (1)

sky_jokerxx
sky_jokerxx

Reputation: 431

You can generate the documents(rst) for the self-made collection using antsibull-docs.
The following is the procedure for generating the documents.

  1. ansible installation

Install ansible.

pip install ansible-base
ansible --version
ansible 2.10.5
  1. antsibull installation

Clone the antsibull repo and install.

pip install --upgrade pip
git clone https://github.com/ansible-community/antsibull.git
cd antsibull/
pip install poetry
poetry install
cd ..
  1. create collections directory

This time, create a collections directory in the current(working) directory.
Change the namespace based on self-made collections.

mkdir -p collections/ansible_collections/{namespace}/
  1. move your collection into the namespace directory
mv {your_collection} collections/ansible_collections/{namespace}/
  1. ansible.cfg creation

Create an ansible.cfg to specify the collection directory path.

vi ansible.cfg

[defaults]
COLLECTIONS_PATHS = {your_working_directory_path}/collections

Check the config is reflected.

ansible-config dump --only-changed
COLLECTIONS_PATHS({your_working_directory_path}/ansible.cfg) = ['{your_working_directory_path}/collections']

Check a module document can be seeing with ansible-doc.

ansible-doc namespace.your_collection.module_name
  1. generate .rst files for the module
mkdir -p build/plugin_docs
antsibull-docs collection --use-current --squash-hierarchy --dest-dir ./build/plugin_docs namespace.your_collection
ls ./build/plugin_docs

With this, the module .rst documents are generated in build/plugin_docs directory.
If a build error occurs, check that there aren't the parameters wrong in galaxy.yml in your_collection directory.

Upvotes: 3

Related Questions